fix: reset proctored exam attempts reliably when the provider is unavailable

[Anas12091101]

Description

When an instructor resets a student's proctored exam, edX also tells the
proctoring provider to delete its copy of the attempt. If the provider was down,
this used to fail with a confusing server error, and a reset could get stuck.

This PR makes the reset ask the provider to delete first, then delete locally,
and handles the provider's reply safely:

• If the provider is down or errors out, the instructor sees a clear "provider is
  temporarily unavailable, please try again" message and the attempt stays put
  (nothing is half-deleted).
• If the provider says the attempt is already gone, that counts as success, so
  trying again works.
• If the provider replies but doesn't confirm the delete, the attempt is kept so it
  can be retried instead of quietly disappearing.
• Every call to the provider now has a timeout (default 30s, configurable per
  backend), so a slow provider can't hang the request.

The reset_attempts admin command was also updated to tell the provider before
deleting, and to stop calling a provider that's down so it doesn't stall.

Testing

Automated: pytest edx_proctoring/tests/test_api.py -k remove_exam_attempt

Manual:

1. Set up a proctored exam and have a learner start an attempt (so it registers
   with the provider).
2. Make the provider unavailable — point its URL at an unreachable host, or make
   its delete call fail.
3. As an instructor, reset that learner's attempt → you see the "try again"
   message and the attempt stays in the list.
4. Bring the provider back and reset again → the reset works and the attempt
   disappears.

Pre-Merge Checklist:

• Updated the version number in edx_proctoring/__init__.py and package.json
• Described your changes in CHANGELOG.rst
• Confirmed Github reports all automated tests/checks are passing
• Approved by at least one additional reviewer

Post-Merge:

• Create a tag matching the new version number

[openedx-webhooks]

Thanks for the pull request, @Anas12091101!

This repository is currently maintained by @openedx/openedx-unmaintained.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

[Copilot]

Pull request overview

Improves reliability of proctored-attempt resets during provider outages.

Changes:

• Moves provider deletion before local deletion and adds typed 502 errors.
• Adds configurable REST request timeouts.
• Expands reset and compatibility tests and releases version 6.1.0.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
package.json	Bumps package version.
edx_proctoring/__init__.py	Bumps Python version.
CHANGELOG.rst	Documents release behavior.
edx_proctoring/api.py	Coordinates provider-first removal.
edx_proctoring/apps.py	Allows timeout configuration.
edx_proctoring/exceptions.py	Adds removal failure exception.
edx_proctoring/handlers.py	Removes provider deletion signal.
edx_proctoring/models.py	Adds best-effort onboarding cleanup.
edx_proctoring/backends/rest.py	Adds attempt-request timeout.
edx_proctoring/backends/tests/test_rest.py	Tests timeout and connection failures.
edx_proctoring/tests/test_api.py	Tests reset failure behavior.
edx_proctoring/tests/test_handlers.py	Removes obsolete signal test.
edx_proctoring/tests/test_views.py	Normalizes DRF validation errors.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Suppressed comments (2)

edx_proctoring/api.py:1938

• The PR description says a provider-supplied error message is preserved when a response body exists, but every exception is replaced with this hard-coded generic text. Consequently, HTTP errors with useful provider details and errors without bodies produce the same client response, and the described with/without-body behavior is not implemented. Preserve an appropriate sanitized provider message when available, with this text as the fallback.

            raise BackendProviderCannotRemoveAttempt(
                # Translators: shown to an instructor when an exam attempt could not be reset
                # because the external proctoring provider is temporarily unavailable.
                'The proctoring provider is temporarily unavailable, so this attempt could not '
                'be fully reset. Please try again in a few minutes.'

edx_proctoring/handlers.py:102

• Removing the model-wide pre_delete receiver means cascading deletes of a ProctoredExam or user now remove registered attempts without notifying the provider; both foreign keys use on_delete=CASCADE (models.py:375-377). The API, onboarding cleanup, and management command cover their own paths, but cascades bypass all three and can leave provider-side attempts orphaned. Add a safe cleanup path for cascades before removing this receiver.

@receiver(pre_save, sender=models.ProctoredExamStudentAttempt)
def on_attempt_changed(sender, instance, signal, **kwargs):

[Copilot]

Pull request overview

Copilot reviewed 15 out of 15 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

edx_proctoring/handlers.py:102

• Removing the pre_delete receiver also removes provider cleanup from every deletion that does not go through the few explicitly updated call sites. In particular, ProctoredExamStudentAttempt.delete_exam_attempt() still directly calls delete(), and deleting a ProctoredExam or user cascades to attempts; all of these previously notified the provider but now leave upstream attempts orphaned. Please provide a safe best-effort fallback for direct/cascade deletes (while avoiding duplicate calls from the strict API path), or route all such deletion entry points through one cleanup service.

@receiver(pre_save, sender=models.ProctoredExamStudentAttempt)
def on_attempt_changed(sender, instance, signal, **kwargs):

edx_proctoring/management/commands/reset_attempts.py:85

• This circuit breaker treats every removal failure as proof that the whole backend is unavailable. _remove_exam_attempt_from_backend uses this same exception for attempt-specific failures too—for example, a 400 HTTP response or one malformed/unconfirmed response—so one bad attempt causes all later valid attempts for that backend to be deleted locally without provider notification. Only suppress later calls for transport/availability failures; continue attempting cleanup after per-attempt errors.

                try:
                    _remove_exam_attempt_from_backend(attempt)
                except BackendProviderCannotRemoveAttempt:

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

edx_proctoring/backends/tests/test_rest.py:288

• This test no longer exercises _make_attempt_request; remove_exam_attempt now builds the request directly. Rename it so failures identify the behavior actually under test.

    def test_make_attempt_request_passes_timeout(self):

edx_proctoring/handlers.py:101

• Removing the pre_delete receiver also removes provider cleanup from deletion paths not routed through the three new helpers, including ORM cascades through the attempt's user and proctored_exam foreign keys (models.py:375-377) and direct model/queryset deletes. Those paths previously notified the provider and will now leave upstream attempts orphaned. Preserve a best-effort signal fallback that is skipped after strict API cleanup, or route every deletion entry point through a centralized cleanup service.

@receiver(pre_save, sender=models.ProctoredExamStudentAttempt)

edx_proctoring/api.py:1948

• This makes a truthy return a new mandatory contract for third-party backends, but the public abstract method only promises to remove the attempt (backends/backend.py:61-65), and custom implementations are supported (docs/backends.rst:350-352). A valid backend that successfully deletes and returns None will now block every reset after a minor-version upgrade. Introduce and document a versioned/capability-based confirmation contract before enforcing it, or release this as a breaking API change.

    if not result:
        # The provider responded but did not confirm removal, so keep the local attempt: a
        # retry can converge once the provider is healthy instead of silently dropping it.
        log.warning('Backend %s did not confirm removal of attempt_id=%s.', exam.backend, attempt.id)
        raise BackendProviderCannotRemoveAttempt(unavailable_message)

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

edx_proctoring/api.py:1923

• The new 502 detail is not surfaced by the existing instructor reset UI. proctored_exam_attempt_view.js:227-239 registers only a success callback for this DELETE request, so on provider failure the instructor sees no “temporarily unavailable” message and the cursor remains stuck on wait, contrary to the PR’s stated behavior. Add an AJAX error handler that displays responseJSON.detail (with a safe fallback), restores the cursor, and cover the failure path in the view spec.

    unavailable_message = _(
        'The proctoring provider is temporarily unavailable, so this attempt could not '
        'be fully reset. Please try again in a few minutes.'
    )