Skip to content

Harden what happens when saving to the database fails - #1437

Merged
microbit-matt-hillsdon merged 6 commits into
home-pagefrom
storage-failure-handling
Nov 20, 2026
Merged

microbit-matt-hillsdon merged 6 commits into
home-pagefrom
storage-failure-handling

Conversation

@microbit-matt-hillsdon

@microbit-matt-hillsdon microbit-matt-hillsdon commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Three gaps in what happens when a save to the projects database fails. From the home-page review: the rest of finding 10, and smaller points S6 and S11.

Unhandled rejections from failed writes

create, update and delete await each request in a transaction and then tx.done. When a request failed, the method threw before reaching tx.done, and the transaction's own rejection had nobody listening. So one failure was reported twice: once to the caller, and once more as an unhandled rejection in error reports.

The transaction's promise is now marked handled when it is created. The caller still gets the request's error, and awaiting tx.done still rejects.

save, which flushes use, already avoided this.

A failed save is no longer the end of the edit

A failed flush dropped its changes. With the database in use the editor had also stopped warning before a tab closes, since every edit is already stored. So after a failed save the edit was in memory only, with the "Failed to save" toast as the only sign, and it was lost on closing the tab or on switching to another project.

  • A change now stays queued until a flush is known to have saved it. A failed flush still sets no timer of its own, so nothing retries for ever against a full quota. But the next flush, whatever causes it, carries everything still unsaved: a later edit, the page being hidden, or the project being switched.
  • Switching project saves what failed, if it can. With storage full, going to the projects page to delete something is the natural remedy. The flush made on switching now includes the failed edit.
  • So does opening the same project again. Clicking back into the project that is already open saves the edit before reloading, and if it still cannot be saved the editor opens on the tab's own copy.
  • The tab warns before closing while the last flush failed. Projects.hasUnsavedChanges exposes that for the open project, and the before-unload check uses it when the database is active. Without the database, and in iframe mode, the check is unchanged.

Keeping changes queued has consequences elsewhere, which are handled:

  • Reloading the open project. Whether for another tab's change or because the user opened it again, the tab first saves anything it has outstanding, so the reload has it too. It takes the project's name from the database first, as the name is the other tab's to change. If its edit still cannot be saved, it keeps its own copy and does not reload. This lives in switchTo, so both callers get it.
  • A deleted project. save() rejects with NoSuchProjectError when the project has gone, and the storage then drops its queue. Otherwise the next flush from a hidden or unloading page, which does not check the project exists, would write part of it back.
  • Last modified. A project is stamped with its latest edit's time, not the time of the first edit in a run of failures.

A cross-tab notice dropped when the list refresh fails

The change handler refreshed the project list first and gave up if that failed, as an unhandled rejection. A delete in another tab could then go unnoticed, leaving the editor on a project that no longer exists. It now logs the failure and carries on to deal with the open project.

For review

  • Still open: a switch while storage is still failing. If the flush made on switching project fails too, the edit is lost with only the toast, as before. Preventing that needs a prompt or a blocked switch, which is left out here.
  • A tab that cannot save does not pick up another tab's changes, and does not catch up by itself. It stays on its own copy until the project is opened in it again or the tab is reloaded, even after its save later succeeds. If it then edits a file the other tab had changed, the other tab's version is overwritten. It needs a failure confined to one tab: a full quota affects both, and then no notice is sent and nothing is skipped.
  • The "Failed to save" toast stays until dismissed, including after a later save has succeeded. The toast API cannot close a single toast.
  • docs/tech-overview.md is updated.

Three gaps from the review of home-page:

- A request failing inside create, update or delete left the transaction's
  completion promise rejecting with nobody listening, so each failure was
  reported a second time as an unhandled rejection. The promise is now
  marked handled; the caller still gets the request's error.

- Closing a tab never warned once the database was in use, on the grounds
  that every edit is already stored. After a failed save that is not true.
  The storage now tracks which files a failed flush left unsaved, until
  they are next saved, and the tab warns before closing while any remain.

- The cross-tab change handler refreshed the project list first and gave
  up if that failed, so a delete in another tab could go unnoticed. It now
  logs the failure and carries on to deal with the open project.
@github-actions

Copy link
Copy Markdown

Preview build will be at
https://review-python.microbit.org/storage-failure-handling/

A failed flush dropped its changes, keeping only the names of the files it
had failed to save. So switching or creating a project lost them: the
flush on switching sent only what was newly pending, and the new project's
storage started with nothing unsaved, which ended the close warning too.
With storage full, going to the projects page to delete something is the
natural remedy, and one click on another project there lost the edit.

A change now stays queued until a flush is known to have saved it. A failed
flush still sets no timer of its own, so nothing retries for ever against a
full quota, but the next flush, whatever causes it, carries everything
still unsaved. That includes the one made when the project is switched.

Unsaved changes are now simply that the last flush failed, in place of
tracking files by name, and the warning clears on the next successful save
of anything.
Keeping a failed save's changes for the next flush had side effects:

- With the project open in two tabs, a failed save in one followed by any
  save in the other left the first out of step. It reloaded from the
  database, losing its edit from the screen, and then the outgoing storage
  wrote that edit to the database. The change handler now saves what this
  tab has outstanding before it reloads, taking the name from the database
  first as the name is the other tab's to change. If that still cannot be
  saved, the tab keeps its copy and does not reload.

- A flush that failed because the project had been deleted was queued like
  any other, and the next urgent flush, which does not check the project
  exists, wrote part of it back. save() now rejects with NoSuchProjectError
  and the storage drops everything on that.

- After a spell of failures the project was stamped with the first failed
  edit's time. It is now stamped with the latest edit's.
Opening the project that is already open took the reload path, which put
the database's copy on screen before the outgoing storage flushed. After a
failed save that lost the edit from the editor while the database gained
it, and the next keystroke wrote the old content back. That is the path
the queue was meant for: storage full, go to the projects page, free some
space, click back into the project.

The cross-tab handler already saved first and skipped the reload if that
failed. That now lives in switchTo's reload branch, so it covers both. The
handler asks for a reload and treats a project that is not there as
deleted.

Also corrects two comments that still said a failed flush's changes are
dropped, and the overview on a tab that cannot save: it stays out of step
until the project is opened in it again or the tab is reloaded.
@microbit-matt-hillsdon

Copy link
Copy Markdown
Collaborator Author

Happy with this now.

@microbit-matt-hillsdon
microbit-matt-hillsdon merged commit 9c6ba5e into home-page Nov 20, 2026
3 checks passed
@microbit-matt-hillsdon
microbit-matt-hillsdon deleted the storage-failure-handling branch November 20, 2026 18:35
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.

1 participant