Make file-backed StoreAsync safe under concurrent writers and readers [patch]

[matt-edmondson]

Fixes #66

What was wrong

FileSystemPersistenceProvider.StoreAsync and TempPersistenceProvider.StoreAsync (and through them ConfigHome and DataHome) had two problems:

• Every writer staged its data in the same <file>.tmp, so overlapping writers to one key moved each other's temp file away and the loser threw.
• The swap deleted the target and then moved the temp file in. In between, a reader saw the key as missing, so RetrieveOrCreateAsync could store a fresh new T() over the real record.

Change

Both providers now go through a new Shared/AtomicFile.cs, linked into each project the same way PersistenceDefaults.cs already is:

• Unique staging file. Each write stages its data in its own <guid>.tmp in the target's directory. The .tmp extension keeps it out of the *<extension> key listings, and a finally always deletes it.
• One-step swap. File.Move(temp, target, overwrite: true) replaces the old file with no delete in between. netstandard2.1 has no such overload, so there it uses File.Replace when the target exists and File.Move when it doesn't. If another writer creates the target in between, the Move throws and the retry takes the Replace path.
• Write retry. Windows won't replace a file while another handle has it open, which a concurrent reader or writer does briefly. The move is retried on IOException/UnauthorizedAccessException, at most 50 times, with delays capped at 20 ms.
• Read retry. RetrieveAsync reads through AtomicFile.ReadAllTextAsync. Windows holds the target exclusively for the instant an overwriting move swaps it, so a read landing then is refused. The first Windows CI run here failed on exactly that. Only ERROR_SHARING_VIOLATION/ERROR_LOCK_VIOLATION are retried; a missing file and every other error still surface at once.

The staging name is deliberately not <file>.<guid>.tmp. PersistenceProviderUtilities budgets each filename for the extension plus .tmp only, and a longer suffix pushes long keys past the 255-byte name limit; an earlier attempt broke Long_Multibyte_Keys_Store_And_Retrieve_On_The_Native_File_System this way. Raising that budget would move where existing long keys get truncated and orphan their stored files.

Tests

Concurrent_Stores_To_One_Key_Never_Throw_Or_Hide_The_Key runs on both FileSystem and Temp. It starts 200 parallel StoreAsync calls to one key while a reader loops over ExistsAsync/RetrieveAsync, then asserts:

• no store or read throws
• the key is never missing
• the final value is one of the payloads that was written
• GetAllKeysAsync lists only that key
• no .tmp file is left behind

Results:

• Without the fix, the test fails on every run on Linux: the reader hits FileNotFoundException in the delete-then-move window.
• With the fix, it passes 5 out of 5 runs on Linux.
• The full Essentials.Tests suite passes (1036), and both provider projects build for every target framework.
• The Windows-only read retry can't be reproduced on Linux; the windows-latest leg is its check.

CLAUDE.md now lists the new shared file. Related but not covered here: #67, the RetrieveOrCreateAsync presence check.

🤖 Generated with Claude Code

https://claude.ai/code/session_01YLmoTmY5N7amW8Z9jazuGV

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.2% Coverage on New Code
1.9% Duplication on New Code

See analysis details on SonarQube Cloud