feat: support File.OpenHandle and RandomAccess in MockFileSystem

[Mpdreamz]

MockFileSystem throws for File.OpenHandle and for every member of RandomAccess since #1542, and the SafeFileHandle overloads of IFile throw NotImplementedException. FileStream.New(handle) does not throw, but passes handle.ToString() on as a path, so it fails with FileNotFoundException. Code that uses handles therefore cannot be tested against the mock. This adds that support, along the lines of what Testably.Abstractions shipped in 7.1.0, adapted to this mock's model.

How it works

SafeFileHandle is sealed and wraps an operating system handle, so the mock cannot create one a real system call would accept. File.OpenHandle hands out a handle with a synthetic value instead (well above any real handle, unique across instances) and an internal registry on MockFileSystem remembers which file it stands for. The handle refers to the MockFileData it opened rather than to its path, so it keeps working after the file is deleted, as it does on a real file system.

• File.OpenHandle opens like MockFileStream does: missing file or directory, CreateNew on an existing file, a directory at the path, a read-only file opened for writing. It takes a file share through FileHandles, so it conflicts with streams exactly as a stream would. Arguments are validated in the runtime's order (FileStreamHelpers.ValidateArguments), so a call with several invalid arguments reports the same one.
• Closing. Because the class is sealed, the mock is not told when a handle is disposed. GetFile, FileExists and the All* enumerations release closed handles before answering: their file share goes, and FileOptions.DeleteOnClose is applied if the same file is still at that path. The sweep runs under the lock on the files, so a thread never misses a handle it closed itself. It costs nothing while no handle is open. The registry holds handles weakly, so a handle that is dropped without being disposed is released once it has been collected, as a real one is by its finalizer.
• RandomAccess reads and writes that file at an offset. Writes replace the contents rather than changing them in place, so an open MockFileStream sees them, and they update the file times. GetLength works through a write-only handle, FlushToDisk validates the handle, and SetLength through a read-only handle throws IOException on Unix (EINVAL) and UnauthorizedAccessException on Windows.
• The SafeFileHandle overloads of IFile read and write the attributes, times and Unix mode of the open file.
• FileStream.New(handle, ...) wraps the file the handle holds open, as FileStream does. It does not open the path again, takes no share of its own, does not apply the handle's FileMode a second time, and closes the handle when it is disposed. It is limited by the handle's own access. It throws ObjectDisposedException once the handle is closed. It validates bufferSize, and rejects an isAsync that differs from the handle's. Targets without FEATURE_RANDOM_ACCESS keep the previous behaviour.
• A behaviour change on net6+: FileStream.New with a handle that did not come from the mock now throws ArgumentException. Before, it opened a file named after handle.ToString().
• A handle from another MockFileSystem, or from the real file system, throws ArgumentException. An accessor that is not a MockFileSystem still gets the NotSupportedException (with an updated message).

There is no public API change: the registry is internal and the members already existed.

Validated against the real file system

Besides the new unit tests, I ran 69 scenarios through both new FileSystem() and new MockFileSystem() and compared the outcome of each: the return value, or the exception type and parameter name. They cover argument validation, open modes, reads, writes, gather/scatter, lengths, access checks, closed and null handles, cancellation, file shares, DeleteOnClose (including through directory enumeration), handles on deleted files, streams built on handles and the handle overloads. I also ran a two-thread stress test of the handle lifetime (200,000 iterations, no misses). On macOS 65 scenarios match. The other 4 are listed below.

Known limitations

• File.Move in this mock copies the MockFileData, so a handle does not follow a file that is moved while it is open.
• The contents are a single array, so an offset beyond Array.MaxLength throws IOException. For an offset that overflows, the runtime throws ArgumentOutOfRangeException instead.
• A MockFileStream refreshes from the shared contents on reads, not on writes. A stream that writes after a RandomAccess.Write to the same file can therefore overwrite it, as two streams on one file already can in this mock.
• SafeFileHandle.IsAsync asks the operating system, so it is false for a mock handle even with FileOptions.Asynchronous. The mock's own isAsync checks use the options the handle was opened with.
• Sharing follows the mock's existing Windows-style rules on every platform. A handle opened with FileShare.Read blocks a writer, just as a MockFileStream does, while on Unix only FileShare.None is enforced.

Found along the way, not changed here

MockFile.Open(path, mode, access, share) ignores share and always opens with FileShare.Read, see MockFile.OpenInternal. The new tests use FileStream.New, which passes the share on. Happy to fix that separately.

Verification

In Release on net8.0, net9.0 and net10.0 (macOS):

• TestingHelpers.Tests: all pass (77 new).
• Wrappers, API and parity tests: all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TymoqrVYgZwdNSper5ZZB1

[Copilot]

Copilot review overview

🟡 Changes recommended

Handle registry concurrency, sharing, option handling, and closed-handle flushing have unresolved correctness issues.

Review effort: Balanced
Findings: 4

Open (4)

• Reject flushes after the adopted handle is closed · New
• Publish the registry atomically for thread-safe lazy initialization · New
• Include BackupOrRestore in the valid FileOptions mask · New
• Enforce active handle shares for delete and move operations · New

What changed in this PR

Adds mock support for file handles, RandomAccess, handle-backed streams, and handle-based metadata operations.

Changes:

• Adds synthetic handle registration and lifecycle management.
• Implements random-access and handle-backed stream operations.
• Adds broad behavioral test coverage and supporting exceptions/resources.

File	Description
MockRandomAccessTests.cs	Tests random-access and handle-backed streams.
MockFileOpenHandleTests.cs	Tests handle opening, lifecycle, and metadata.
Resources.resx	Adds handle-related error messages.
MockSafeFileHandles.cs	Implements synthetic handle registry.
MockRandomAccess.cs	Implements random-access operations.
MockFileSystem.cs	Integrates handle cleanup.
MockFileStreamFactory.cs	Creates streams from mock handles.
MockFileStream.cs	Adds handle-backed stream behavior.
MockFile.cs	Implements handle APIs and metadata overloads.
CommonExceptions.cs	Adds exception factories.

---

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

[Mpdreamz]

Fixed in 67e514f. Flush, Flush(bool) and FlushAsync now throw ObjectDisposedException once the handle is closed, and disposing the stream still succeeds. I checked both against the real file system: FileStream behaves the same way.

[Mpdreamz]

Fixed in 67e514f. The registry is now published with LazyInitializer.EnsureInitialized, so threads that make their first call at the same time share one registry. There's a test that opens 16 handles in parallel on a fresh file system, 20 times over, and then resolves each of them.

[Mpdreamz]

Right, the real File.OpenHandle accepts BackupOrRestore (I checked on .NET 10). I added it to the mask in 67e514f, with a test. The mask is the only place the check happens, so this also covers the second location you mentioned.

[Mpdreamz]

A correction to my reply above: the runtime accepts BackupOrRestore only from .NET 9. .NET 8 still rejects it, which I found when running the same check in the sibling library's tests, since those also run against the real file system. As of d69dd99 the mock accepts it on net9.0 and later and rejects it on net8.0 and earlier, with a test for each.

[Mpdreamz]

True, but this was already the case before this PR: MockFileStream registers its share in FileHandles the same way, and File.Delete/File.Move only look at MockFileData.AllowedFileShare. So a stream opened without FileShare.Delete doesn't block a delete today either. Making delete and move respect open shares would change how existing streams behave too, so I'd rather do that in a separate PR, and I'm happy to if you want it.