diff --git a/docs/adr/ADR-0044.md b/docs/adr/ADR-0044.md index ef3f630c..8f411bf5 100644 --- a/docs/adr/ADR-0044.md +++ b/docs/adr/ADR-0044.md @@ -2,7 +2,7 @@ id: ADR-0044 title: Layered Virtual File System (VFS) Mount-Point and Logical URI Routing Architecture date: 2026-11-01 -status: proposed +status: accepted authors: - mallory-scotton deciders: @@ -21,7 +21,7 @@ deciders: > `cache://`, `temp://`), isolating gameplay, shader, and asset streaming code from physical disk > layouts and console sandbox partitions. -![Proposed][badge-proposed] +![Accepted][badge-accepted] ## Context @@ -224,6 +224,8 @@ multiple physical directories into a single logical hierarchy. `gp::application`, `gp::launch`). * [ADR-0043](./ADR-0043.md): Zero-Allocation `.bss` Folder Discovery and Stack `PathBuffer` in `gp::platform::Paths`. +* [ADR-0060](./ADR-0060.md): Zero-Allocation OS `FileHandle`, Positional `readAt`/`writeAt`, Atomic + Writes, and Stack Directory Iteration in `gp::platform::FileSystem`. **Canonical references:** diff --git a/docs/adr/ADR-0060.md b/docs/adr/ADR-0060.md new file mode 100644 index 00000000..9f0a079e --- /dev/null +++ b/docs/adr/ADR-0060.md @@ -0,0 +1,335 @@ +--- +id: ADR-0060 +title: >- + Layer 0 OS FileHandle, Positional I/O, Atomic Writes, and Stack Directory Iteration in + gp::platform::FileSystem +date: 2026-11-19 +status: accepted +authors: + - mallory-scotton +deciders: + - mallory-scotton + - nathan-fievet + - hugo-cathelain +--- + + +# ADR-0060: Layer 0 OS `FileHandle`, Positional I/O, Atomic Writes, and Directory Iteration + +> Establishes `gp::platform::FileSystem` and `gp::platform::FileHandle` in `gp::core` as the +> Layer 0 OS file and directory I/O subsystem. It pairs non-polymorphic RAII file descriptors with +> lock-free positional I/O (`pread`/`pwrite` and Win32 `OVERLAPPED`), atomic write-and-rename +> transactions (`writeAtomic`), and stack-buffered directory traversal (`iterateDirectory`) below +> Layer 1 `gp::vfs::VirtualFileSystem` ([ADR-0044](./ADR-0044.md)). + +![Accepted][badge-accepted] + +## Context + +`gp::platform::Paths` ([ADR-0043](./ADR-0043.md)) resolves standard OS directories and normalizes +paths in `gp::PathBuffer` (`gp::FixedString<1024>`) without heap allocations. To support early-boot +subsystems (crash dump writers, log file sinks, dynamic library loaders, config parsers) and Layer 1 +`gp::vfs::VirtualFileSystem` ([ADR-0044](./ADR-0044.md)), the engine also needs OS file and +directory I/O primitives (`open`, `read`, `write`, `readAt`, `writeAt`, `exists`, `getStats`, +`createDirectory`, `createDirectoryTree`, `removeFile`, `removeDirectoryTree`, `move`, `copyFile`, +`iterateDirectory`, and bulk or atomic file helpers). + +Raw OS file and directory APIs introduce five engineering problems in a game engine: + +1. **Multi-Fiber File Pointer Races (`Seek` + `Read` vs. Positional `readAt`):** + Object-oriented file wrappers like Unreal Engine's `IFileHandle::Seek()` and `Read()` mutate a + single stateful cursor inside the OS kernel file description. When multiple worker fibers in + `gp::thread::JobSystem` ([ADR-0052](./ADR-0052.md)) read different chunks from the same open + archive or binary file, a shared cursor forces every fiber to take a mutex per handle. OS kernels + already provide stateless positional I/O: POSIX `pread`/`pwrite` and Win32 `ReadFile`/`WriteFile` + with an explicit `OVERLAPPED` 64-bit offset. Positional I/O lets worker fibers read disjoint + byte ranges from one `FileHandle` concurrently without locks. +2. **Virtual Dispatch and Heap Allocation at Layer 0:** + Wrapping every OS descriptor in a heap-allocated `IFileHandle*` behind a chain of `IPlatformFile` + decorators triggers `malloc`/`free` calls on every open and extra vtable indirections on every + syscall. Early-boot crash handlers and pre-main logger sinks cannot safely call heap-allocating + file APIs before custom memory allocators ([ADR-0042](./ADR-0042.md)) initialize. +3. **Heap-Allocating Directory Enumeration (`std::filesystem::directory_iterator`):** + Standard library directory iterators and naive wrappers allocate `std::vector` + lists on the heap during traversal. Scanning a shader cache or asset directory with 20,000 files + creates tens of thousands of transient string allocations and fragments the heap. +4. **Save-Game and Config Corruption on Crash (`writeAtomic`):** + Opening an existing save or config file with `CreateAlways` (`O_TRUNC`) destroys the previous + contents before the new payload reaches disk. If the process crashes, loses power, or hits a + disk-full error mid-write, the user loses the file to a zero-byte or half-written state. +5. **Cross-Platform UTF-16 vs. UTF-8 and Epoch Differences:** + * **Windows (Win32):** Expects UTF-16 `wchar_t` paths in `CreateFileW`, `GetFileAttributesExW`, + `CreateDirectoryW`, `FindFirstFileExW` (`FindExInfoBasic` + `FIND_FIRST_EX_LARGE_FETCH`), + `MoveFileExW` (`MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH`), and `CopyFileW`. + Timestamps arrive as 64-bit `FILETIME` ticks (100-ns intervals since January 1, 1601 UTC). + * **POSIX (Linux & macOS):** Consumes UTF-8 `char` paths in `open`, `stat`/`fstat`/`lstat`, + `mkdir`, `opendir`/`readdir`, `unlink`, `rmdir`, `rename`, and `fsync`. Timestamps arrive as + `struct timespec` seconds and nanoseconds since the Unix Epoch (January 1, 1970 UTC). + +## Decision + +We introduce `gp::platform::FileSystem` and `gp::platform::FileHandle` in `gp::core` as the Layer 0 +OS filesystem abstraction, paired with Layer 1 `gp::vfs::VirtualFileSystem` +([ADR-0044](./ADR-0044.md)) in `gp::core/vfs/`. + +### 1. Physical Module & Header Granularity Layout + +Following the **Header Granularity Law** and [ADR-0006](./ADR-0006.md), Layer 0 (`gp::platform`) +and Layer 1 (`gp::vfs`) headers and unit tests are split by role: + +```text +source/runtime/core/ +├── public/ +│ ├── platforms/ +│ │ ├── base/ +│ │ │ └── system/ +│ │ │ ├── FileEnums.hpp • FileError, FileAccessMode, FileOpenMode, +│ │ │ │ FileShareMode, FileSeekOrigin, +│ │ │ │ FileAttributeFlags, DirectoryVisitControl +│ │ │ ├── FileTypes.hpp • NativeFileDescriptor, FileStats, +│ │ │ │ DirectoryEntry, DirectoryVisitorFn +│ │ │ ├── FileHandle.hpp • Non-polymorphic RAII OS file handle +│ │ │ └── FileSystem.hpp • Platform alias (gp::platform::) +│ │ ├── generic/ +│ │ │ └── system/ +│ │ │ └── GenericFileSystem.hpp • Recursive trees, bulk I/O, writeAtomic +│ │ ├── windows/ +│ │ │ └── system/ +│ │ │ └── WindowsFileSystem.hpp • Win32 CreateFileW, OVERLAPPED I/O +│ │ ├── unix/ +│ │ │ └── system/ +│ │ │ └── UnixFileSystem.hpp • POSIX open, pread/pwrite, stat, opendir +│ │ ├── linux/ +│ │ │ └── system/ +│ │ │ └── LinuxFileSystem.hpp • Linux platform inheritance alias +│ │ ├── apple/ +│ │ │ └── system/ +│ │ │ └── AppleFileSystem.hpp • Apple/Darwin platform inheritance alias +│ │ └── macos/ +│ │ └── system/ +│ │ └── MacOSFileSystem.hpp • macOS platform inheritance alias +│ └── vfs/ +│ ├── VfsForward.hpp • Forward declarations for VFS types +│ ├── VfsEnums.hpp • VfsError, MountPriority, MountAccess +│ ├── VfsTypes.hpp • ParsedUri, MountPointDesc, VfsDirectoryEntry +│ ├── IMountBackend.hpp • Abstract mount backend contract +│ ├── PhysicalMountBackend.hpp • OS directory backend + sandbox jail +│ ├── MemoryMountBackend.hpp • In-memory backend for tests & embedded blobs +│ └── VirtualFileSystem.hpp • Priority-layered URI scheme router +├── private/ +│ ├── platforms/ +│ │ ├── generic/system/GenericFileSystem.cpp +│ │ ├── windows/system/WindowsFileSystem.cpp +│ │ ├── unix/system/UnixFileSystem.cpp +│ │ ├── linux/system/LinuxFileSystem.cpp +│ │ ├── apple/system/AppleFileSystem.cpp +│ │ └── macos/system/MacOSFileSystem.cpp +│ └── vfs/ +│ ├── PhysicalMountBackend.cpp +│ ├── MemoryMountBackend.cpp +│ └── VirtualFileSystem.cpp +└── tests/ + ├── platforms/ + │ └── base/ + │ └── system/ + │ └── FileSystem.tests.cpp • GTest suite for Layer 0 FileSystem & handle + └── vfs/ + └── VirtualFileSystem.tests.cpp • GTest suite for Layer 1 VFS & sandbox jail +``` + +### 2. Layer 0 Value-Type `FileHandle` & Lock-Free Positional I/O + +`gp::platform::FileHandle` is an 8-byte, move-only, non-polymorphic RAII wrapper around +`NativeFileDescriptor` (`void*` Win32 `HANDLE` initialized to `INVALID_HANDLE_VALUE` on Windows; +`Int32` file descriptor initialized to `-1` on POSIX): + +```cpp +namespace gp::platform +{ + +class GP_CORE_API FileHandle final +{ +public: + [[nodiscard]] FileHandle() noexcept = default; + [[nodiscard]] explicit FileHandle(const NativeFileDescriptor descriptor) noexcept; + ~FileHandle() noexcept; + + FileHandle(const FileHandle&) = delete; + FileHandle& operator=(const FileHandle&) = delete; + [[nodiscard]] FileHandle(FileHandle&& other) noexcept; + FileHandle& operator=(FileHandle&& other) noexcept; + + [[nodiscard]] bool isValid() const noexcept; + [[nodiscard]] explicit operator bool() const noexcept; + [[nodiscard]] NativeFileDescriptor nativeDescriptor() const noexcept; + [[nodiscard]] NativeFileDescriptor release() noexcept; + + gp::Expected close() noexcept; + [[nodiscard]] gp::Expected + read(void* const outBuffer, const gp::USize bytesToRead) noexcept; + [[nodiscard]] gp::Expected + write(const void* const buffer, const gp::USize bytesToWrite) noexcept; + + [[nodiscard]] gp::Expected readAt( + const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead + ) const noexcept; + [[nodiscard]] gp::Expected writeAt( + const gp::UInt64 offset, const void* const buffer, const gp::USize bytesToWrite + ) noexcept; + + [[nodiscard]] gp::Expected + seek(const gp::Int64 offset, const FileSeekOrigin origin = FileSeekOrigin::Begin) noexcept; + [[nodiscard]] gp::Expected tell() const noexcept; + [[nodiscard]] gp::Expected size() const noexcept; + gp::Expected flush() noexcept; + gp::Expected truncate(const gp::UInt64 newSize) noexcept; + +private: + NativeFileDescriptor m_descriptor{ kInvalidNativeFileDescriptor }; +}; + +} // namespace gp::platform +``` + +### 3. Architectural Invariants + +1. **Zero Heap Allocations Across Layer 0 Syscalls:** + * Path conversions at the OS boundary (`UTF-8` `gp::StringView` to null-terminated `PathBuffer` + on POSIX, or stack `wchar_t[kMaxPathLength + 16]` via `MultiByteToWideChar` on Windows) happen + on the calling thread's stack. + * `FileSystem::open()`, `exists()`, `isFile()`, `isDirectory()`, `fileSize()`, `getStats()`, + `setReadOnly()`, `createDirectory()`, `createDirectoryTree()`, `removeFile()`, + `removeDirectory()`, `removeDirectoryTree()`, `move()`, `copyFile()`, and `iterateDirectory()` + allocate 0 bytes on the heap. +2. **Thread-Safe Positional `readAt` / `writeAt` Contract:** + * On POSIX, `FileHandle::readAt` and `FileHandle::writeAt` call `::pread` and `::pwrite` + (retrying automatically on `EINTR` or partial transfers), which execute atomically with respect + to the file offset. + * On Windows, `FileHandle::readAt` and `FileHandle::writeAt` populate a stack `OVERLAPPED` + struct (`Offset` and `OffsetHigh`) and pass it to `::ReadFile` / `::WriteFile`, so concurrent + worker fibers can read from one handle without locking. +3. **Canonical Unix Epoch Nanoseconds in `FileStats` ([ADR-0030](./ADR-0030.md)):** + * `FileStats` holds `size` (`gp::UInt64`), `creationTime`, `lastWriteTime`, `lastAccessTime` + (`gp::time::Timestamp`), and `attributes` (`FileAttributeFlags`: `None`, `RegularFile`, + `Directory`, `ReadOnly`, `Hidden`, `SymbolicLink`). + * All platforms convert file timestamps to 64-bit unsigned nanoseconds since the Unix Epoch + (`1970-01-01T00:00:00Z`). Windows converts `FILETIME` via + `(ticks100ns - 116444736000000000ULL) * 100ULL`; POSIX converts `struct timespec` via + `tv_sec * 1'000'000'000ULL + tv_nsec`. +4. **Crash-Safe Atomic File Replacement (`writeAtomic`):** + * `FileSystem::writeAtomic(path, data, size)` never truncates the target file in place. It + writes the payload to a sibling staging file (`.tmp.` using a process-wide atomic + sequence counter and `FileOpenMode::CreateNew`), calls `FileHandle::flush()` + (`FlushFileBuffers` / `fsync`), closes the handle, and executes an atomic OS rename + (`MoveFileExW` with `MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH` on Windows; `::rename` + on POSIX). If any step fails, the staging file is unlinked and the original file stays intact. +5. **Stack Directory Enumeration (`iterateDirectory` & `iterateDirectoryRecursive`):** + * Directory iteration accepts either a stateless C callback + `(const DirectoryEntry& entry, void* userData) -> DirectoryVisitControl` or any C++ callable + `(const DirectoryEntry& entry) -> DirectoryVisitControl` (`Continue`, `SkipSubdirectory`, + `Stop`). + * `DirectoryEntry` exposes non-owning `gp::StringView` slices (`path`, `name`) pointing into the + iterator frame's stack `PathBuffer`, along with `FileStats` populated directly from + `WIN32_FIND_DATAW` on Windows so no extra `GetFileAttributesExW` syscall is needed per entry. + * The OS iterator filters out `.` and `..` pseudo-entries automatically. +6. **Container-Templated Bulk Read Helpers (`readAllBytes`, `readAllText`):** + * `FileSystem::readAllBytes(path, outBuffer)` accepts any 1-byte element container + (`gp::Vector`, `gp::String`), and `readAllText(path, outString)` accepts + any `gp::container::BasicString` satisfying `gp::concepts::IsAllocator` + ([ADR-0042](./ADR-0042.md)). Callers can load files directly into a `LinearAllocator` or + `FiberScratchAllocator` ([ADR-0048](./ADR-0048.md)) with a single `resizeUninitialized` call. + +## Alternatives Considered + +### Option A: Unreal Engine Polymorphic `IPlatformFile` / `IFileHandle*` Decorator Stack at Layer 0 + +Expose all OS file operations through a virtual `IPlatformFile` singleton returning heap-allocated +`IFileHandle*` pointers. + +**Why rejected:** Forces a heap allocation on every `openRead`/`openWrite`, adds chained virtual +call overhead to every file query, and blurs the boundary between Layer 0 OS syscalls and Layer 1 +VFS URI mount routing ([ADR-0044](./ADR-0044.md)). + +### Option B: C Standard Library `FILE*` (`fopen` / `fread` / `fwrite` / `fseek`) + +Implement Layer 0 file handles on top of `` `FILE*` streams. + +**Why rejected:** +1. `` has no portable positional `pread`/`pwrite` equivalent, making lock-free concurrent + reads from a shared handle across job-system fibers impossible. +2. `FILE*` allocates an internal heap buffer (`BUFSIZ`, typically 4 to 8 KiB) on `fopen` and takes + an internal CRT lock (`_lock_file`) on every `fread`/`fwrite`, double-buffering data the engine + already reads into caller buffers. +3. Standard `fopen` on Windows does not accept UTF-8 paths without non-standard `_wfopen_s` + extensions and lacks granular `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE` control. + +### Option C: C++17 `` and `` + +Use `std::filesystem` for directory operations and `std::ifstream`/`std::ofstream` for file I/O. + +**Why rejected:** Forbidden by `gp-engine`'s zero-STL-allocation and `-fno-exceptions` rules. Both +`` and `` rely on locales, virtual `std::streambuf` dispatch, hidden heap +allocations, and exception-throwing overloads or allocating `std::error_code` path conversions. + +## Consequences + +### Positive + +- **Zero Heap Allocations Across All Layer 0 OS Primitives.** File opening, reading, writing, + seeking, stat queries, directory creation, atomic file replacement, and directory iteration + allocate 0 bytes on the heap. +- **Lock-Free Multi-Fiber Positional Streaming (`readAt`).** Multiple worker fibers in + `gp::thread::JobSystem` can read concurrently from a single open `FileHandle` via `OVERLAPPED` / + `pread` without mutex contention. +- **Zero-Syscall Metadata During Windows Directory Iteration.** Populating `DirectoryEntry::stats` + directly from `WIN32_FIND_DATAW` during `FindFirstFileExW` / `FindNextFileW` avoids $N$ extra + `GetFileAttributesExW` kernel transitions when scanning large directories. +- **Crash-Safe Save & Config Integrity (`writeAtomic`).** User saves and engine configuration + files are protected against partial-write corruption via flushed temporary staging files and + atomic OS rename swaps. +- **Clean Foundation for Layer 1 `gp::vfs::VirtualFileSystem` ([ADR-0044](./ADR-0044.md)).** + `gp::vfs::PhysicalMountBackend` wraps `gp::platform::FileSystem` directly while adding logical + URI routing, priority overlays, and sandbox escape protection. + +### Negative + +- **Platform-Specific Implementation Maintenance.** Maintaining direct Win32 + (`WindowsFileSystem.cpp`) and POSIX (`UnixFileSystem.cpp`) syscall backends requires mapping + `GetLastError()` and `errno` into `gp::platform::FileError`. +- **Recursion Depth Bound on `iterateDirectoryRecursive`.** Stack-allocated recursive directory + traversal uses ~1.1 KiB of stack space per nesting level (`PathBuffer` per depth), so it is capped + at `kMaxDirectoryRecursionDepth = 32` (~35 KiB max stack) to remain safe inside 64 KiB standard + fibers ([ADR-0049](./ADR-0049.md)). + +## Rationale and Cross-References + +- [ADR-0006](./ADR-0006.md): Co-Located Documentation, Tests, and Benchmarks per Module. +- [ADR-0030](./ADR-0030.md): 64-Bit Integer Nanoseconds and Rational Frame Rates as Canonical Time + Units (`gp::time::Timestamp` used in `FileStats`). +- [ADR-0042](./ADR-0042.md): Lifetime-Scoped Arena Allocators and `gp::concepts::IsAllocator` + (used by `readAllBytes` / `readAllText`). +- [ADR-0043](./ADR-0043.md): Zero-Allocation `.bss` Folder Discovery and `PathBuffer` in + `gp::platform::Paths`. +- [ADR-0044](./ADR-0044.md): Layered Virtual File System (VFS) Mount-Point and Logical URI Routing + Architecture. +- [ADR-0049](./ADR-0049.md): Dual-Tier Platform Execution Contexts and Scratch-Bound Cooperative + Fibers (`64 KiB` standard fiber stack budget). + +**Canonical references:** + +- id Software, *DOOM 3 BFG / id Tech 4 Source Code* (`neo/sys/win32/win_main.cpp`, + `neo/sys/posix/posix_main.cpp`, `neo/framework/File.h`). +- Epic Games, *Unreal Engine 5 Source Code* + (`Engine/Source/Runtime/Core/Private/Windows/WindowsPlatformFile.cpp`, + `Private/Unix/UnixPlatformFile.cpp`). +- Microsoft Win32 Documentation, *Synchronous and Asynchronous I/O (`ReadFile` with `OVERLAPPED` + offset)* and *`FindFirstFileExW` (`FindExInfoBasic`, `FIND_FIRST_EX_LARGE_FETCH`)*. +- IEEE Std 1003.1 (POSIX.1-2017), *`pread()`, `pwrite()`, `rename()`, and `fsync()` System + Interfaces*. + + +[badge-proposed]: https://img.shields.io/badge/Status-Proposed-yellow.svg +[badge-accepted]: https://img.shields.io/badge/Status-Accepted-brightgreen.svg +[badge-rejected]: https://img.shields.io/badge/Status-Rejected-red.svg +[badge-deprecated]: https://img.shields.io/badge/Status-Deprecated-lightgrey.svg +[badge-superseded]: https://img.shields.io/badge/Status-Superseded-lightgrey.svg diff --git a/docs/adr/INDEX.md b/docs/adr/INDEX.md index d85dc6bb..0ef0e06f 100644 --- a/docs/adr/INDEX.md +++ b/docs/adr/INDEX.md @@ -367,6 +367,14 @@ Hardware Abstraction Layer (HAL). > and mod override layers, to logical URI schemes (`engine://`, `game://`, `user://`, > `appdata://`, `cache://`, `temp://`), isolating gameplay, shader, and asset streaming code from > physical disk layouts and console sandbox partitions. +- [**ADR-0060**: Zero-Allocation OS `FileHandle`, Positional `readAt`/`writeAt`, Atomic Writes, and + Stack Directory Iteration in `gp::platform::FileSystem`](./ADR-0060.md) + > Establishes `gp::platform::FileSystem` and `gp::platform::FileHandle` in `gp::core` as the + > Layer 0 zero-heap-allocation OS file and directory I/O subsystem, pairing non-polymorphic RAII + > OS file descriptors with lock-free positional I/O (`pread`/`pwrite` and Win32 `OVERLAPPED` + > offsets), crash-safe atomic write-and-rename transactions (`writeAtomic`), and zero-allocation + > stack-buffered directory tree traversal (`iterateDirectory`) below Layer 1 + > `gp::vfs::VirtualFileSystem` ([ADR-0044](./ADR-0044.md)). ### Concurrency & Event Routing diff --git a/gp-engine.code-workspace b/gp-engine.code-workspace index 47962849..9da027d3 100644 --- a/gp-engine.code-workspace +++ b/gp-engine.code-workspace @@ -175,6 +175,7 @@ "appleclang": "assembly", "gcc": "assembly", "intel": "assembly", + "vfs": "dump", "platforms": "client", "es": "i18n", "fr": "i18n", diff --git a/source/launch/editor/private/Main.cpp b/source/launch/editor/private/Main.cpp index 5e80ecfe..15929e9b 100644 --- a/source/launch/editor/private/Main.cpp +++ b/source/launch/editor/private/Main.cpp @@ -15,6 +15,7 @@ #include "miscellaneous/CommandLine.hpp" #include "profiling/Profiler.hpp" #include "profiling/ProfilingControl.hpp" +#include "vfs/VirtualFileSystem.hpp" #include namespace gp @@ -62,6 +63,14 @@ class EditorApplication : public Application "EditorApplication::OnInitialize", GP_U32_COLOR_PURPLE, profiling::ProfilingControl::isZonesEnabled() ); + // TODO(vfs): Mount editor-only content schemes here (e.g., `editor://` pointing to the editor resources root, + // plus any active project or developer override layers) once the editor asset directory layout is + // defined. The six base ADR-0044 schemes (`engine://`, `game://`, `user://`, `appdata://`, + // `cache://`, `temp://`) are already mounted by `Application::initializeInternal()`. + GP_LOG_INFO( + LogEditor, "VirtualFileSystem Ready ({} active mounts).", gp::vfs::VirtualFileSystem::getMountCount() + ); + const gp::console::IConsoleManager& consoleMgr = getConsoleManager(); GP_LOG_INFO( LogEditor, @@ -127,7 +136,7 @@ class EditorApplication : public Application std::fputs( "\n========================================================\n" " [TEMP] Console Stdin Shell Active\n" - " Examples: help | cvar.list | cvar.dump | prof.Status | log.Stats | app.Stats | jobs.Stats\n" + " Examples: help | cvar.list | cvar.dump | prof.Status | log.Stats | app.Stats | jobs.Stats | vfs.Status | vfs.Mounts\n" " Set CVar: t.TimeScale 0.5 | app.TargetFps=60 | log.GlobalLevel Warning\n" " Commands: 'resume' (or Enter) returns to gp-editor | 'quit' / 'app.Quit' exits\n" "========================================================\n", diff --git a/source/runtime/application/private/Application.cpp b/source/runtime/application/private/Application.cpp index de8d5492..348b281a 100644 --- a/source/runtime/application/private/Application.cpp +++ b/source/runtime/application/private/Application.cpp @@ -13,12 +13,16 @@ #include "input/GenericInputSystem.hpp" #include "logging/LogFormatter.hpp" #include "miscellaneous/CommandLine.hpp" +#include "platforms/base/system/PathTypes.hpp" #include "profiling/Profiler.hpp" #include "profiling/ProfilingControl.hpp" +#include "templates/Expected.hpp" #include "templates/Optional.hpp" #include "threading/roles/ThreadRole.hpp" #include "threading/roles/ThreadRoleEnums.hpp" #include "threading/roles/ThreadRoleTypes.hpp" +#include "vfs/VfsEnums.hpp" +#include "vfs/VirtualFileSystem.hpp" namespace gp { @@ -196,6 +200,55 @@ void Application::applyCommandLineOverrides() noexcept m_desc.fileSink.filePath = *customLogPath; } } + + const Optional optVfs = CommandLine::tryGetBool("vfs"); + if (optVfs.hasValue()) + { + m_desc.enableVirtualFileSystem = *optVfs; + } + + const Optional optVfsApp = CommandLine::tryGetString("vfs-app"); + if (optVfsApp.hasValue() && !optVfsApp->isEmpty()) + { + m_desc.vfsAppName = *optVfsApp; + } +} + +vfs::VfsError Application::initializeVirtualFileSystemInternal() noexcept +{ + if (!m_desc.enableVirtualFileSystem) + { + return vfs::VfsError::None; + } + + // Preserve pre-configured mounts if the host or test harness mounted schemes before Application::run(). + if (vfs::VirtualFileSystem::getMountCount() > 0u) + { + m_ownsVfsInitialization = false; + return vfs::VfsError::None; + } + + const gp::StringView effectiveAppName = !m_desc.vfsAppName.isEmpty() ? m_desc.vfsAppName : m_desc.backend.appName; + const gp::Expected mountRes = + vfs::VirtualFileSystem::initializeDefaultMounts(effectiveAppName); + if (!mountRes.hasValue()) [[unlikely]] + { + vfs::VirtualFileSystem::shutdown(); + m_ownsVfsInitialization = false; + return mountRes.error(); + } + + m_ownsVfsInitialization = true; + return vfs::VfsError::None; +} + +void Application::shutdownVirtualFileSystemInternal() noexcept +{ + if (m_ownsVfsInitialization) + { + vfs::VirtualFileSystem::shutdown(); + m_ownsVfsInitialization = false; + } } bool Application::attachThreadRolesInternal() noexcept @@ -311,7 +364,26 @@ void Application::initializeLoggingInternal() noexcept if (m_desc.enableFileLogSink) { - if (m_fileSink.open(m_desc.fileSink) == log::LogResult::Success) + log::FileSinkDesc resolvedFileSinkDesc = m_desc.fileSink; + gp::PathBuffer resolvedLogPath{}; + bool canOpenFileSink = true; + + if (!resolvedFileSinkDesc.filePath.isEmpty() && resolvedFileSinkDesc.filePath.contains("://")) + { + const gp::Expected resolved = + vfs::VirtualFileSystem::resolveWritablePhysicalPath(resolvedFileSinkDesc.filePath); + if (resolved.hasValue()) + { + resolvedLogPath = resolved.value(); + resolvedFileSinkDesc.filePath = resolvedLogPath.view(); + } + else + { + canOpenFileSink = false; + } + } + + if (canOpenFileSink && m_fileSink.open(resolvedFileSinkDesc) == log::LogResult::Success) { (void)logger.addSink(&m_fileSink); } @@ -633,12 +705,21 @@ bool Application::initializeInternal() noexcept ); applyCommandLineOverrides(); + const vfs::VfsError vfsInitError = initializeVirtualFileSystemInternal(); initializeLoggingInternal(); (void)console::IConsoleManager::get(); + if (vfsInitError != vfs::VfsError::None) [[unlikely]] + { + GP_LOG_ERROR( + LogApplication, "VirtualFileSystem default mount initialization failed ({}).", vfs::toString(vfsInitError) + ); + } + if (!attachThreadRolesInternal()) [[unlikely]] { shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -663,6 +744,7 @@ bool Application::initializeInternal() noexcept ); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -676,6 +758,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } } @@ -687,6 +770,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -705,6 +789,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } } @@ -732,6 +817,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } } @@ -766,6 +852,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -785,6 +872,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -805,6 +893,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } @@ -827,6 +916,7 @@ bool Application::initializeInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); return false; } } @@ -885,6 +975,7 @@ void Application::shutdownInternal() noexcept m_eventStream.shutdown(); detachThreadRolesInternal(); shutdownLoggingInternal(); + shutdownVirtualFileSystemInternal(); m_isInitialized = false; } diff --git a/source/runtime/application/public/Application.hpp b/source/runtime/application/public/Application.hpp index 0143eae4..6ab82c96 100644 --- a/source/runtime/application/public/Application.hpp +++ b/source/runtime/application/public/Application.hpp @@ -45,6 +45,7 @@ #include "threading/jobs/JobSystem.hpp" #include "threading/roles/NamedThreadDispatcher.hpp" #include "time/EngineClock.hpp" +#include "vfs/VfsForward.hpp" #include "window/IWindow.hpp" #include "window/WindowDesc.hpp" // IWYU pragma: keep @@ -111,6 +112,7 @@ class GP_APPLICATION_API Application gp::Atomic m_isRunning{ false }; bool m_isInitialized{ false }; bool m_isSuspended{ false }; + bool m_ownsVfsInitialization{ false }; bool m_ownsLoggerInitialization{ false }; bool m_ownsGameThreadRole{ false }; bool m_ownsRenderThreadRole{ false }; @@ -473,10 +475,20 @@ class GP_APPLICATION_API Application {} private: - /// @brief Applies command-line concurrency and logging overrides (`-threads`, `-workers`, `-no-jobsystem`, - /// `-core-affinity`, `-no-log`, `-no-console-log`, `-log-file`) from `gp::CommandLine` to `m_desc`. + /// @brief Applies command-line concurrency, logging, and VFS overrides (`-threads`, `-workers`, `-no-jobsystem`, + /// `-core-affinity`, `-no-log`, `-no-console-log`, `-log-file`, `-no-vfs`, `-vfs-app`) from + /// `gp::CommandLine` to `m_desc`. void applyCommandLineOverrides() noexcept; + /// @brief Mounts the six default ADR-0044 VFS schemes when `m_desc.enableVirtualFileSystem` is true and no mounts + /// are already registered by the caller. + /// @return `vfs::VfsError::None` on success (or if skipped), or the error returned by + /// `VirtualFileSystem::initializeDefaultMounts()`. + [[nodiscard]] vfs::VfsError initializeVirtualFileSystemInternal() noexcept; + + /// @brief Unmounts all VFS mount points via `VirtualFileSystem::shutdown()` if this `Application` initialized them. + void shutdownVirtualFileSystemInternal() noexcept; + /// @brief Claims `NamedThread::Game` (and `Render` / `RHI` when `singleThreadedRenderAndRHI` is set) for the /// calling thread. /// @return True if all requested roles were attached or already held by the caller, false if another thread owns diff --git a/source/runtime/application/public/ApplicationDesc.hpp b/source/runtime/application/public/ApplicationDesc.hpp index 2bbcb3f5..e38853ed 100644 --- a/source/runtime/application/public/ApplicationDesc.hpp +++ b/source/runtime/application/public/ApplicationDesc.hpp @@ -6,6 +6,7 @@ #include "ApplicationTypes.hpp" #include "backend/ApplicationBackendDesc.hpp" +#include "containers/views/StringView.hpp" // IWYU pragma: keep #include "CoreMinimal.hpp" #include "logging/LogDesc.hpp" #include "threading/jobs/JobSystemDesc.hpp" @@ -45,6 +46,12 @@ struct ApplicationDesc /// @brief Configuration for the built-in buffered `FileSink` ([ADR-0054]). log::FileSinkDesc fileSink{}; + /// @brief Optional application subfolder name passed to `gp::vfs::VirtualFileSystem::initializeDefaultMounts()` + /// ([ADR-0044]). + /// @details When empty, `Application` falls back to `backend.appName` (and `VirtualFileSystem` falls back to the + /// executable stem if that is also empty). Can be overridden via `-vfs-app=` on the command line. + gp::StringView vfsAppName{}; + /// @brief Byte capacity of the lock-free SPSC event stream (automatically rounded up to a power of two). gp::USize eventRingBufferBytes{ 16384u }; @@ -96,6 +103,11 @@ struct ApplicationDesc /// @brief If true, registers the application's `TracySink` with `Logger::instance()`. bool enableTracyLogSink{ true }; + + /// @brief If true, mounts the six default ADR-0044 VFS schemes (`engine://`, `game://`, `user://`, `appdata://`, + /// `cache://`, `temp://`) during startup and unmounts them on exit (can be overridden by `-no-vfs` on the + /// command line). + bool enableVirtualFileSystem{ true }; }; } // namespace gp diff --git a/source/runtime/application/tests/Application.tests.cpp b/source/runtime/application/tests/Application.tests.cpp index 1515dc32..33e4954a 100644 --- a/source/runtime/application/tests/Application.tests.cpp +++ b/source/runtime/application/tests/Application.tests.cpp @@ -14,7 +14,10 @@ #include "logging/sinks/MemoryRingSink.hpp" #include "memory/MemoryOrder.hpp" #include "miscellaneous/CommandLine.hpp" +#include "platforms/base/system/FileSystem.hpp" +#include "platforms/base/system/Paths.hpp" #include "platforms/base/system/Thread.hpp" +#include "templates/ScopeExit.hpp" // IWYU pragma: keep #include "threading/atomics/Atomic.hpp" // IWYU pragma: keep #include "threading/jobs/JobGraph.hpp" #include "threading/jobs/JobSystem.hpp" @@ -23,6 +26,8 @@ #include "threading/roles/ScopedThreadRole.hpp" #include "threading/roles/ThreadRole.hpp" #include "threading/roles/ThreadRoleEnums.hpp" +#include "vfs/MemoryMountBackend.hpp" +#include "vfs/VirtualFileSystem.hpp" #include namespace gp::tests @@ -1050,4 +1055,267 @@ TEST(ApplicationThreadRoleWiringTest, FailsInitIfAnotherThreadAlreadyOwnsGameRol EXPECT_FALSE(thread::ThreadRoleRegistry::isAttached(thread::NamedThread::Game)); } +TEST(ApplicationVfsWiringTest, DefaultMountsLifecycleAndConsoleDiagnostics) +{ + CommandLine::shutdown(); + vfs::VirtualFileSystem::shutdown(); + + auto cleanup = gp::makeScopeExit( + []() noexcept -> void + { + vfs::VirtualFileSystem::shutdown(); + CommandLine::shutdown(); + } + ); + + ApplicationDesc desc{}; + desc.backend.appName = "GPAppVfsLifecycleUnitTest"; + desc.createMainWindow = false; + desc.enableLogging = false; + desc.enableJobSystem = false; + desc.targetForegroundFps = 0.0; + desc.targetBackgroundFps = 0.0; + + class VfsLifecycleProbeApp final : public Application + { + public: + explicit VfsLifecycleProbeApp(const ApplicationDesc& inDesc) noexcept + : Application(inDesc) + {} + + bool allSchemesMountedInInit{ false }; + bool vfsStillActiveInShutdown{ false }; + bool consoleStatusReportedSix{ false }; + gp::PathBuffer tempResolvedPath{}; + + protected: + [[nodiscard]] virtual bool onInitialize() noexcept override + { + allSchemesMountedInInit = vfs::VirtualFileSystem::isSchemeMounted("engine://") && + vfs::VirtualFileSystem::isSchemeMounted("game://") && + vfs::VirtualFileSystem::isSchemeMounted("user://") && + vfs::VirtualFileSystem::isSchemeMounted("appdata://") && + vfs::VirtualFileSystem::isSchemeMounted("cache://") && + vfs::VirtualFileSystem::isSchemeMounted("temp://") && + (vfs::VirtualFileSystem::getMountCount() == 6u); + + const gp::Expected tempRes = + vfs::VirtualFileSystem::resolveWritablePhysicalPath("temp://probe.txt"); + if (tempRes.hasValue()) + { + tempResolvedPath = tempRes.value(); + } + + gp::String output{}; + console::ConsoleOutputDelegate capture = console::ConsoleOutputDelegate::createLambda( + [&output](const gp::StringView line) noexcept -> void + { + output.append(line); + output.pushBack('\n'); + } + ); + const console::ConsoleResult cmdRes = executeConsoleCommand("vfs.Status", &capture); + consoleStatusReportedSix = + (cmdRes == console::ConsoleResult::Success) && output.view().contains("total=6/"); + return true; + } + + virtual void onUpdate(const gp::time::FrameTimeStats&) noexcept override + { + requestQuit(); + } + + virtual void onShutdown() noexcept override + { + vfsStillActiveInShutdown = (vfs::VirtualFileSystem::getMountCount() == 6u); + } + }; + + VfsLifecycleProbeApp app(desc); + EXPECT_EQ(app.run(), 0); + EXPECT_TRUE(app.allSchemesMountedInInit); + EXPECT_TRUE(app.consoleStatusReportedSix); + EXPECT_TRUE(app.vfsStillActiveInShutdown); + EXPECT_TRUE(app.tempResolvedPath.view().contains("GPAppVfsLifecycleUnitTest")); + + // Application owned VFS initialization, so shutdownInternal() must unmount all default schemes cleanly. + EXPECT_EQ(vfs::VirtualFileSystem::getMountCount(), 0u); +} + +TEST(ApplicationVfsWiringTest, CommandLineNoVfsDisablesDefaultMountsAndPreservesPreMountedBackends) +{ + CommandLine::shutdown(); + vfs::VirtualFileSystem::shutdown(); + + auto cleanup = gp::makeScopeExit( + []() noexcept -> void + { + vfs::VirtualFileSystem::shutdown(); + CommandLine::shutdown(); + } + ); + + // 1. Verify -no-vfs disables default mounts cleanly. + CommandLine::initialize("gp_app_test -no-vfs"); + ASSERT_TRUE(CommandLine::isInitialized()); + { + ApplicationDesc desc{}; + desc.createMainWindow = false; + desc.enableLogging = false; + desc.enableJobSystem = false; + desc.targetForegroundFps = 0.0; + desc.targetBackgroundFps = 0.0; + + class NoVfsProbeApp final : public Application + { + public: + explicit NoVfsProbeApp(const ApplicationDesc& inDesc) noexcept + : Application(inDesc) + {} + + gp::USize mountCountInInit{ 99u }; + + protected: + [[nodiscard]] virtual bool onInitialize() noexcept override + { + mountCountInInit = vfs::VirtualFileSystem::getMountCount(); + return true; + } + + virtual void onUpdate(const gp::time::FrameTimeStats&) noexcept override + { + requestQuit(); + } + }; + + NoVfsProbeApp app(desc); + EXPECT_EQ(app.run(), 0); + EXPECT_EQ(app.mountCountInInit, 0u); + EXPECT_EQ(vfs::VirtualFileSystem::getMountCount(), 0u); + } + + // 2. Verify pre-mounted caller backends are preserved and not torn down by Application::shutdownInternal(). + CommandLine::shutdown(); + vfs::MemoryMountBackend customMem{}; + ASSERT_TRUE( + vfs::VirtualFileSystem::mountBackend( + "custom://", &customMem, vfs::MountPriority::Base, vfs::MountAccess::ReadWrite + ) + .hasValue() + ); + + { + ApplicationDesc desc{}; + desc.createMainWindow = false; + desc.enableLogging = false; + desc.enableJobSystem = false; + desc.targetForegroundFps = 0.0; + desc.targetBackgroundFps = 0.0; + + class PreMountedProbeApp final : public Application + { + public: + explicit PreMountedProbeApp(const ApplicationDesc& inDesc) noexcept + : Application(inDesc) + {} + + bool customMounted{ false }; + gp::USize totalMounts{ 0u }; + + protected: + [[nodiscard]] virtual bool onInitialize() noexcept override + { + customMounted = vfs::VirtualFileSystem::isSchemeMounted("custom://"); + totalMounts = vfs::VirtualFileSystem::getMountCount(); + return true; + } + + virtual void onUpdate(const gp::time::FrameTimeStats&) noexcept override + { + requestQuit(); + } + }; + + PreMountedProbeApp app(desc); + EXPECT_EQ(app.run(), 0); + EXPECT_TRUE(app.customMounted); + EXPECT_EQ(app.totalMounts, 1u); + } + + EXPECT_TRUE(vfs::VirtualFileSystem::isSchemeMounted("custom://")); + EXPECT_EQ(vfs::VirtualFileSystem::getMountCount(), 1u); + EXPECT_TRUE(vfs::VirtualFileSystem::unmountBackend("custom://", &customMem)); +} + +TEST(ApplicationVfsWiringTest, CommandLineVfsAppAndVfsLogFileUriResolution) +{ + CommandLine::shutdown(); + vfs::VirtualFileSystem::shutdown(); + + const gp::PathBuffer expectedRoot = + gp::platform::Paths::combine(gp::platform::Paths::tempDir(), "GPAppVfsLogUriUnitTest"); + gp::platform::FileSystem::removeDirectoryTree(expectedRoot.view()); + + auto cleanup = gp::makeScopeExit( + [&expectedRoot]() noexcept -> void + { + vfs::VirtualFileSystem::shutdown(); + CommandLine::shutdown(); + gp::platform::FileSystem::removeDirectoryTree(expectedRoot.view()); + } + ); + + CommandLine::initialize("gp_app_test -vfs-app=GPAppVfsLogUriUnitTest -log-file=temp://logs/vfs_boot.log"); + ASSERT_TRUE(CommandLine::isInitialized()); + + ApplicationDesc desc{}; + desc.createMainWindow = false; + desc.enableLogging = true; + desc.enableConsoleLogSink = false; + desc.enableDebugOutputLogSink = false; + desc.enableTracyLogSink = false; + desc.enableFileLogSink = false; // Enabled by -log-file CLI override + desc.logger.mode = log::LogExecutionMode::Synchronous; + desc.logger.applyCommandLineOverrides = false; + desc.enableJobSystem = false; + desc.targetForegroundFps = 0.0; + desc.targetBackgroundFps = 0.0; + + class VfsLogProbeApp final : public Application + { + public: + explicit VfsLogProbeApp(const ApplicationDesc& inDesc) noexcept + : Application(inDesc) + {} + + bool fileSinkWasOpen{ false }; + gp::PathBuffer openedLogPath{}; + + protected: + [[nodiscard]] virtual bool onInitialize() noexcept override + { + fileSinkWasOpen = getFileSink().isOpen(); + openedLogPath.assign(getFileSink().getFilePath()); + GP_LOG_INFO(LogApplication, "VfsLogProbeApp marker message"); + return true; + } + + virtual void onUpdate(const gp::time::FrameTimeStats&) noexcept override + { + requestQuit(); + } + }; + + VfsLogProbeApp app(desc); + EXPECT_EQ(app.run(), 0); + EXPECT_TRUE(app.fileSinkWasOpen); + EXPECT_TRUE(app.openedLogPath.view().contains("GPAppVfsLogUriUnitTest")); + EXPECT_TRUE(app.openedLogPath.view().endsWith("logs/vfs_boot.log")); + EXPECT_EQ(vfs::VirtualFileSystem::getMountCount(), 0u); + + gp::String diskLog{}; + ASSERT_TRUE(gp::platform::FileSystem::readAllText(app.openedLogPath.view(), diskLog).hasValue()); + EXPECT_TRUE(diskLog.view().contains("VfsLogProbeApp marker message")); +} + } // namespace gp::tests diff --git a/source/runtime/core/private/logging/sinks/FileSink.cpp b/source/runtime/core/private/logging/sinks/FileSink.cpp index 10acf7d4..d0b28043 100644 --- a/source/runtime/core/private/logging/sinks/FileSink.cpp +++ b/source/runtime/core/private/logging/sinks/FileSink.cpp @@ -6,8 +6,11 @@ #include "containers/strings/FixedString.hpp" #include "logging/LogFormatter.hpp" #include "memory/Memory.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileSystem.hpp" #include "platforms/base/system/Paths.hpp" -#include +#include "templates/Expected.hpp" +#include namespace gp::log { @@ -59,43 +62,38 @@ LogResult FileSink::open(const FileSinkDesc& desc) noexcept return LogResult::InvalidArguments; } - const char* const openMode = desc.truncateOnOpen ? "wb" : "ab"; -#if GP_PLATFORM_WINDOWS - std::FILE* rawFile = nullptr; - const errno_t err = ::fopen_s(&rawFile, m_filePath.cString(), openMode); - if (err != 0 || rawFile == nullptr) + const gp::StringView parentDir = gp::platform::Paths::getPath(m_filePath.view()); + if (!parentDir.isEmpty() && !gp::platform::FileSystem::isDirectory(parentDir)) { - m_fileHandle = nullptr; - return LogResult::IoError; + gp::platform::FileSystem::createDirectoryTree(parentDir); } - m_fileHandle = rawFile; -#else - std::FILE* const rawFile = std::fopen(m_filePath.cString(), openMode); - if (rawFile == nullptr) + + const gp::platform::FileOpenMode openMode = + desc.truncateOnOpen ? gp::platform::FileOpenMode::CreateAlways : gp::platform::FileOpenMode::Append; + gp::Expected openResult = gp::platform::FileSystem::open( + m_filePath.view(), gp::platform::FileAccessMode::Write, openMode, gp::platform::FileShareMode::Read + ); + if (!openResult.hasValue()) { - m_fileHandle = nullptr; return LogResult::IoError; } - m_fileHandle = rawFile; -#endif + m_fileHandle = std::move(openResult.value()); return LogResult::Success; } void FileSink::close() noexcept { - if (m_fileHandle != nullptr) + if (m_fileHandle.isValid()) { flush(); - std::FILE* const rawFile = static_cast(m_fileHandle); - std::fclose(rawFile); - m_fileHandle = nullptr; + m_fileHandle.close(); } } void FileSink::write(const LogRecordView& record) noexcept { - if (m_fileHandle == nullptr || !shouldWrite(record.level)) + if (!m_fileHandle.isValid() || !shouldWrite(record.level)) { return; } @@ -122,9 +120,12 @@ void FileSink::write(const LogRecordView& record) noexcept } else { - std::FILE* const rawFile = static_cast(m_fileHandle); - const gp::USize written = std::fwrite(formattedLine.data(), sizeof(char), lineLen, rawFile); - m_totalBytesWritten += static_cast(written); + const gp::Expected writeRes = + m_fileHandle.write(formattedLine.data(), lineLen); + if (writeRes.hasValue()) + { + m_totalBytesWritten += static_cast(writeRes.value()); + } } const bool flushEvery = (m_flags & LogSinkFlags::FlushEveryRecord) != LogSinkFlags::None; @@ -136,26 +137,28 @@ void FileSink::write(const LogRecordView& record) noexcept void FileSink::flush() noexcept { - if (m_fileHandle == nullptr) + if (!m_fileHandle.isValid()) { return; } flushInternalBuffer(); - std::FILE* const rawFile = static_cast(m_fileHandle); - std::fflush(rawFile); + m_fileHandle.flush(); } void FileSink::flushInternalBuffer() noexcept { - if (m_fileHandle == nullptr || m_bufferedBytes == 0u) + if (!m_fileHandle.isValid() || m_bufferedBytes == 0u) { return; } - std::FILE* const rawFile = static_cast(m_fileHandle); - const gp::USize written = std::fwrite(m_writeBuffer, sizeof(char), m_bufferedBytes, rawFile); - m_totalBytesWritten += static_cast(written); + const gp::Expected writeRes = + m_fileHandle.write(m_writeBuffer, m_bufferedBytes); + if (writeRes.hasValue()) + { + m_totalBytesWritten += static_cast(writeRes.value()); + } m_bufferedBytes = 0u; } diff --git a/source/runtime/core/private/platforms/apple/system/AppleFileSystem.cpp b/source/runtime/core/private/platforms/apple/system/AppleFileSystem.cpp new file mode 100644 index 00000000..191aebec --- /dev/null +++ b/source/runtime/core/private/platforms/apple/system/AppleFileSystem.cpp @@ -0,0 +1,5 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/apple/system/AppleFileSystem.hpp" diff --git a/source/runtime/core/private/platforms/generic/system/GenericFileSystem.cpp b/source/runtime/core/private/platforms/generic/system/GenericFileSystem.cpp new file mode 100644 index 00000000..289f4507 --- /dev/null +++ b/source/runtime/core/private/platforms/generic/system/GenericFileSystem.cpp @@ -0,0 +1,200 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/generic/system/GenericFileSystem.hpp" + +namespace gp::platform::generic +{ + +gp::Expected FileSystem::open( + const gp::StringView path, const FileAccessMode access, const FileOpenMode openMode, const FileShareMode shareMode +) noexcept +{ + (void)path; + (void)access; + (void)openMode; + (void)shareMode; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected + FileSystem::openRead(const gp::StringView path, const FileShareMode shareMode) noexcept +{ + return open(path, FileAccessMode::Read, FileOpenMode::OpenExisting, shareMode); +} + +gp::Expected FileSystem::openWrite( + const gp::StringView path, const bool append, const bool allowRead, const FileShareMode shareMode +) noexcept +{ + const FileAccessMode access = allowRead ? FileAccessMode::ReadWrite : FileAccessMode::Write; + const FileOpenMode mode = append ? FileOpenMode::Append : FileOpenMode::CreateAlways; + return open(path, access, mode, shareMode); +} + +gp::Expected FileSystem::getStats(const gp::StringView path) noexcept +{ + (void)path; + return gp::makeUnexpected(FileError::NotSupported); +} + +bool FileSystem::exists(const gp::StringView path) noexcept +{ + return getStats(path).hasValue(); +} + +bool FileSystem::isFile(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + return stats.hasValue() && stats.value().isFile(); +} + +bool FileSystem::isDirectory(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + return stats.hasValue() && stats.value().isDirectory(); +} + +bool FileSystem::isReadOnly(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + return stats.hasValue() && stats.value().isReadOnly(); +} + +gp::Expected FileSystem::setReadOnly(const gp::StringView path, const bool readOnly) noexcept +{ + (void)path; + (void)readOnly; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::fileSize(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + if (!stats.hasValue()) + { + return gp::makeUnexpected(stats.error()); + } + if (stats.value().isDirectory()) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + return stats.value().size; +} + +gp::Expected FileSystem::createDirectory(const gp::StringView path) noexcept +{ + (void)path; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::createDirectoryTree(const gp::StringView path) noexcept +{ + return createDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::removeFile(const gp::StringView path) noexcept +{ + (void)path; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::removeDirectory(const gp::StringView path) noexcept +{ + (void)path; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::removeDirectoryTree(const gp::StringView path) noexcept +{ + return removeDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + (void)sourcePath; + (void)destinationPath; + (void)overwrite; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + (void)sourcePath; + (void)destinationPath; + (void)overwrite; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + (void)directoryPath; + (void)visitor; + (void)userData; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + bool stopped = false; + return iterateDirectoryRecursiveImpl(directoryPath, visitor, userData, 0u, stopped); +} + +gp::Expected + FileSystem::readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept +{ + (void)path; + (void)outBuffer; + (void)bufferCapacity; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected + FileSystem::writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + (void)path; + (void)data; + (void)sizeInBytes; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::writeAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + (void)path; + (void)data; + (void)sizeInBytes; + return gp::makeUnexpected(FileError::NotSupported); +} + +gp::Expected FileSystem::appendAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return appendAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + return writeAtomicImpl(path, data, sizeInBytes); +} + +gp::Expected FileSystem::writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAtomic(path, text.data(), text.size()); +} + +} // namespace gp::platform::generic diff --git a/source/runtime/core/private/platforms/linux/system/LinuxFileSystem.cpp b/source/runtime/core/private/platforms/linux/system/LinuxFileSystem.cpp new file mode 100644 index 00000000..c7036da2 --- /dev/null +++ b/source/runtime/core/private/platforms/linux/system/LinuxFileSystem.cpp @@ -0,0 +1,5 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/linux/system/LinuxFileSystem.hpp" diff --git a/source/runtime/core/private/platforms/macos/system/MacOSFileSystem.cpp b/source/runtime/core/private/platforms/macos/system/MacOSFileSystem.cpp new file mode 100644 index 00000000..f6c2a835 --- /dev/null +++ b/source/runtime/core/private/platforms/macos/system/MacOSFileSystem.cpp @@ -0,0 +1,5 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/macos/system/MacOSFileSystem.hpp" diff --git a/source/runtime/core/private/platforms/unix/system/UnixFileSystem.cpp b/source/runtime/core/private/platforms/unix/system/UnixFileSystem.cpp new file mode 100644 index 00000000..bd28ddc4 --- /dev/null +++ b/source/runtime/core/private/platforms/unix/system/UnixFileSystem.cpp @@ -0,0 +1,1013 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/unix/system/UnixFileSystem.hpp" +#include "platforms/base/system/Paths.hpp" +#include +#include +#include +#include +#include +#include +#include + +namespace gp::platform::unix::detail +{ + +/// @brief Maps a POSIX `errno` value to the canonical engine `gp::platform::FileError` enumeration. +/// @param[in] posixErrno Raw `errno` integer value. +/// @return Mapped `FileError` enum value. +[[nodiscard]] static FileError mapPosixErrno(const int posixErrno) noexcept +{ + switch (posixErrno) + { + case 0: + return FileError::None; + case ENOENT: + return FileError::NotFound; + case EEXIST: + return FileError::AlreadyExists; + case EACCES: + case EPERM: + return FileError::AccessDenied; + case EROFS: + return FileError::ReadOnlyFileSystem; + case EAGAIN: +#if defined(EWOULDBLOCK) && (EWOULDBLOCK != EAGAIN) + case EWOULDBLOCK: +#endif + case ETXTBSY: + return FileError::SharingViolation; + case ENAMETOOLONG: + case ELOOP: + return FileError::InvalidPath; + case EBADF: + return FileError::InvalidHandle; + case EINVAL: + case ESPIPE: + return FileError::InvalidArgument; + case EISDIR: + return FileError::IsDirectory; + case ENOTDIR: + return FileError::NotDirectory; + case ENOTEMPTY: + return FileError::DirectoryNotEmpty; + case ENOSPC: + case EDQUOT: + return FileError::DiskFull; + case EMFILE: + case ENFILE: + return FileError::TooManyOpenFiles; + case EXDEV: + return FileError::CrossDeviceLink; + default: + return FileError::IoFailure; + } +} + +/// @brief Normalizes a UTF-8 `gp::StringView` into a null-terminated `PathBuffer` for POSIX syscalls. +/// @param[in] utf8Path Input UTF-8 path view. +/// @param[out] outPath Destination `PathBuffer`. +/// @param[in] trimTrailingSlash If true, removes redundant trailing slashes. +/// @return True if `outPath` is non-empty and fits within `kMaxPathLength`, false otherwise. +[[nodiscard]] static bool + toPosixPath(const gp::StringView utf8Path, PathBuffer& outPath, const bool trimTrailingSlash = false) noexcept +{ + outPath.clear(); + if (utf8Path.isEmpty() || utf8Path.size() > kMaxPathLength) + { + return false; + } + + outPath.assign(utf8Path); + if (trimTrailingSlash) + { + Paths::normalizeDirectoryName(outPath); + } + else + { + Paths::normalizeFilename(outPath); + } + + return !outPath.isEmpty(); +} + +/// @brief Converts POSIX `seconds` and `nanoseconds` into a `gp::time::Timestamp` (nanoseconds since Unix Epoch). +/// @param[in] sec Signed seconds since 1970-01-01T00:00:00Z. +/// @param[in] nsec Nanosecond sub-second offset. +/// @return Normalized `gp::time::Timestamp`. +[[nodiscard]] static gp::time::Timestamp timespecToTimestamp(const gp::Int64 sec, const gp::Int64 nsec) noexcept +{ + if (sec <= 0) + { + return gp::time::Timestamp(0ULL); + } + const gp::UInt64 totalNs = + static_cast(sec) * 1'000'000'000ULL + (nsec > 0 ? static_cast(nsec) : 0ULL); + return gp::time::Timestamp(totalNs); +} + +/// @brief Populates a `FileStats` structure from a POSIX `struct stat` and leaf filename. +/// @param[in] st Populated `struct stat` from `::lstat` or `::stat`. +/// @param[in] isSymlink True if `lstat` detected `S_ISLNK(lstatBuf.st_mode)`. +/// @param[in] leafName Clean leaf filename (used to detect POSIX dot-prefixed hidden files). +/// @return Populated `FileStats` snapshot. +[[nodiscard]] static FileStats + buildStatsFromPosixStat(const struct stat& st, const bool isSymlink, const gp::StringView leafName) noexcept +{ + FileStats stats{}; + const bool isDir = S_ISDIR(st.st_mode); + stats.size = isDir ? 0ULL : static_cast(st.st_size); + +#if GP_PLATFORM_APPLE || GP_PLATFORM_MACOS + stats.lastWriteTime = timespecToTimestamp( + static_cast(st.st_mtimespec.tv_sec), static_cast(st.st_mtimespec.tv_nsec) + ); + stats.lastAccessTime = timespecToTimestamp( + static_cast(st.st_atimespec.tv_sec), static_cast(st.st_atimespec.tv_nsec) + ); + stats.creationTime = timespecToTimestamp( + static_cast(st.st_birthtimespec.tv_sec), static_cast(st.st_birthtimespec.tv_nsec) + ); +#else + stats.lastWriteTime = + timespecToTimestamp(static_cast(st.st_mtim.tv_sec), static_cast(st.st_mtim.tv_nsec)); + stats.lastAccessTime = + timespecToTimestamp(static_cast(st.st_atim.tv_sec), static_cast(st.st_atim.tv_nsec)); + stats.creationTime = stats.lastWriteTime; +#endif + + if (stats.creationTime.nanoseconds == 0ULL) + { + stats.creationTime = stats.lastWriteTime; + } + + FileAttributeFlags flags = isDir ? FileAttributeFlags::Directory : FileAttributeFlags::RegularFile; + if ((st.st_mode & (S_IWUSR | S_IWGRP | S_IWOTH)) == 0) + { + flags = flags | FileAttributeFlags::ReadOnly; + } + if (!leafName.isEmpty() && leafName[0] == '.' && leafName != "." && leafName != "..") + { + flags = flags | FileAttributeFlags::Hidden; + } + if (isSymlink) + { + flags = flags | FileAttributeFlags::SymbolicLink; + } + + stats.attributes = flags; + return stats; +} + +} // namespace gp::platform::unix::detail + +namespace gp::platform +{ + +gp::Expected FileHandle::close() noexcept +{ + if (!isValid()) + { + return true; + } + + const int fd = m_descriptor; + m_descriptor = kInvalidNativeFileDescriptor; + + if (::close(fd) != 0 && errno != EINTR) + { + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + return true; +} + +gp::Expected FileHandle::read(void* const outBuffer, const gp::USize bytesToRead) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToRead == 0u) + { + return 0u; + } + if (outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Byte* dst = static_cast(outBuffer); + gp::USize totalRead = 0u; + + while (totalRead < bytesToRead) + { + const gp::USize remaining = bytesToRead - totalRead; + const ssize_t n = ::read(m_descriptor, dst + totalRead, remaining); + if (n < 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + if (n == 0) + { + break; + } + totalRead += static_cast(n); + } + + return totalRead; +} + +gp::Expected FileHandle::write(const void* const buffer, const gp::USize bytesToWrite) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToWrite == 0u) + { + return 0u; + } + if (buffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const gp::Byte* src = static_cast(buffer); + gp::USize totalWritten = 0u; + + while (totalWritten < bytesToWrite) + { + const gp::USize remaining = bytesToWrite - totalWritten; + const ssize_t n = ::write(m_descriptor, src + totalWritten, remaining); + if (n < 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + if (n == 0) + { + break; + } + totalWritten += static_cast(n); + } + + return totalWritten; +} + +gp::Expected + FileHandle::readAt(const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead) const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToRead == 0u) + { + return 0u; + } + if (outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Byte* dst = static_cast(outBuffer); + gp::USize totalRead = 0u; + + while (totalRead < bytesToRead) + { + const gp::USize remaining = bytesToRead - totalRead; + const off_t currentOffset = static_cast(offset + static_cast(totalRead)); + const ssize_t n = ::pread(m_descriptor, dst + totalRead, remaining, currentOffset); + if (n < 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + if (n == 0) + { + break; + } + totalRead += static_cast(n); + } + + return totalRead; +} + +gp::Expected + FileHandle::writeAt(const gp::UInt64 offset, const void* const buffer, const gp::USize bytesToWrite) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToWrite == 0u) + { + return 0u; + } + if (buffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const gp::Byte* src = static_cast(buffer); + gp::USize totalWritten = 0u; + + while (totalWritten < bytesToWrite) + { + const gp::USize remaining = bytesToWrite - totalWritten; + const off_t currentOffset = static_cast(offset + static_cast(totalWritten)); + const ssize_t n = ::pwrite(m_descriptor, src + totalWritten, remaining, currentOffset); + if (n < 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + if (n == 0) + { + break; + } + totalWritten += static_cast(n); + } + + return totalWritten; +} + +gp::Expected FileHandle::seek(const gp::Int64 offset, const FileSeekOrigin origin) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + int whence = SEEK_SET; + switch (origin) + { + case FileSeekOrigin::Begin: + whence = SEEK_SET; + break; + case FileSeekOrigin::Current: + whence = SEEK_CUR; + break; + case FileSeekOrigin::End: + whence = SEEK_END; + break; + default: + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const off_t newPos = ::lseek(m_descriptor, static_cast(offset), whence); + if (newPos < 0) + { + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + + return static_cast(newPos); +} + +gp::Expected FileHandle::tell() const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + const off_t currentPos = ::lseek(m_descriptor, 0, SEEK_CUR); + if (currentPos < 0) + { + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + + return static_cast(currentPos); +} + +gp::Expected FileHandle::size() const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + struct stat st{}; + if (::fstat(m_descriptor, &st) != 0) + { + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + + return static_cast(st.st_size); +} + +gp::Expected FileHandle::flush() noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + while (::fsync(m_descriptor) != 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + + return true; +} + +gp::Expected FileHandle::truncate(const gp::UInt64 newSize) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + while (::ftruncate(m_descriptor, static_cast(newSize)) != 0) + { + if (errno == EINTR) + { + continue; + } + return gp::makeUnexpected(unix::detail::mapPosixErrno(errno)); + } + + return true; +} + +} // namespace gp::platform + +namespace gp::platform::unix +{ + +gp::Expected FileSystem::open( + const gp::StringView path, + const FileAccessMode access, + const FileOpenMode openMode, + [[maybe_unused]] const FileShareMode shareMode +) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + int flags = 0; +#ifdef O_CLOEXEC + flags |= O_CLOEXEC; +#endif + + const bool canRead = gp::enums::hasAllFlags(access, FileAccessMode::Read); + const bool canWrite = gp::enums::hasAllFlags(access, FileAccessMode::Write); + if (canRead && canWrite) + { + flags |= O_RDWR; + } + else if (canRead) + { + flags |= O_RDONLY; + } + else if (canWrite) + { + flags |= O_WRONLY; + } + else + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + switch (openMode) + { + case FileOpenMode::OpenExisting: + break; + case FileOpenMode::CreateAlways: + flags |= (O_CREAT | O_TRUNC); + break; + case FileOpenMode::CreateNew: + flags |= (O_CREAT | O_EXCL); + break; + case FileOpenMode::OpenAlways: + flags |= O_CREAT; + break; + case FileOpenMode::Append: + flags |= (O_CREAT | O_APPEND); + break; + default: + return gp::makeUnexpected(FileError::InvalidArgument); + } + + int fd = -1; + do + { + fd = ::open(posixPath.cString(), flags, 0644); + } + while (fd < 0 && errno == EINTR); + + if (fd < 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + struct stat st{}; + if (::fstat(fd, &st) == 0 && S_ISDIR(st.st_mode)) + { + ::close(fd); + return gp::makeUnexpected(FileError::IsDirectory); + } + + return FileHandle(fd); +} + +gp::Expected + FileSystem::openRead(const gp::StringView path, const FileShareMode shareMode) noexcept +{ + return open(path, FileAccessMode::Read, FileOpenMode::OpenExisting, shareMode); +} + +gp::Expected FileSystem::openWrite( + const gp::StringView path, const bool append, const bool allowRead, const FileShareMode shareMode +) noexcept +{ + const FileAccessMode access = allowRead ? FileAccessMode::ReadWrite : FileAccessMode::Write; + const FileOpenMode mode = append ? FileOpenMode::Append : FileOpenMode::CreateAlways; + return open(path, access, mode, shareMode); +} + +gp::Expected FileSystem::getStats(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + struct stat lstatBuf{}; + if (::lstat(posixPath.cString(), &lstatBuf) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + const bool isSymlink = S_ISLNK(lstatBuf.st_mode); + struct stat targetStat = lstatBuf; + if (isSymlink) + { + if (::stat(posixPath.cString(), &targetStat) != 0) + { + targetStat = lstatBuf; + } + } + + return detail::buildStatsFromPosixStat(targetStat, isSymlink, Paths::getPathLeaf(posixPath.view())); +} + +bool FileSystem::exists(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return false; + } + + struct stat st{}; + return ::stat(posixPath.cString(), &st) == 0 || ::lstat(posixPath.cString(), &st) == 0; +} + +bool FileSystem::isFile(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return false; + } + + struct stat st{}; + return ::stat(posixPath.cString(), &st) == 0 && S_ISREG(st.st_mode); +} + +bool FileSystem::isDirectory(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return false; + } + + struct stat st{}; + return ::stat(posixPath.cString(), &st) == 0 && S_ISDIR(st.st_mode); +} + +bool FileSystem::isReadOnly(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + return stats.hasValue() && stats.value().isReadOnly(); +} + +gp::Expected FileSystem::setReadOnly(const gp::StringView path, const bool readOnly) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + struct stat st{}; + if (::stat(posixPath.cString(), &st) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + mode_t newMode = st.st_mode; + if (readOnly) + { + newMode &= ~static_cast(S_IWUSR | S_IWGRP | S_IWOTH); + } + else + { + newMode |= static_cast(S_IWUSR); + } + + if (::chmod(posixPath.cString(), newMode) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + return true; +} + +gp::Expected FileSystem::fileSize(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + if (!stats.hasValue()) + { + return gp::makeUnexpected(stats.error()); + } + if (stats.value().isDirectory()) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + return stats.value().size; +} + +gp::Expected FileSystem::createDirectory(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (::mkdir(posixPath.cString(), 0755) != 0) + { + const int err = errno; + if (err == EEXIST) + { + struct stat st{}; + if (::stat(posixPath.cString(), &st) == 0 && S_ISDIR(st.st_mode)) + { + return true; + } + return gp::makeUnexpected(FileError::AlreadyExists); + } + return gp::makeUnexpected(detail::mapPosixErrno(err)); + } + + return true; +} + +gp::Expected FileSystem::createDirectoryTree(const gp::StringView path) noexcept +{ + return createDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::removeFile(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (::unlink(posixPath.cString()) != 0) + { + const int err = errno; + if (err == EPERM || err == EISDIR) + { + struct stat st{}; + if (::lstat(posixPath.cString(), &st) == 0 && S_ISDIR(st.st_mode)) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + } + return gp::makeUnexpected(detail::mapPosixErrno(err)); + } + + return true; +} + +gp::Expected FileSystem::removeDirectory(const gp::StringView path) noexcept +{ + PathBuffer posixPath{}; + if (!detail::toPosixPath(path, posixPath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + struct stat st{}; + if (::lstat(posixPath.cString(), &st) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + if (!S_ISDIR(st.st_mode)) + { + return gp::makeUnexpected(FileError::NotDirectory); + } + + if (::rmdir(posixPath.cString()) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + return true; +} + +gp::Expected FileSystem::removeDirectoryTree(const gp::StringView path) noexcept +{ + return removeDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + PathBuffer posixSrc{}; + PathBuffer posixDst{}; + if (!detail::toPosixPath(sourcePath, posixSrc, true) || !detail::toPosixPath(destinationPath, posixDst, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (!overwrite && exists(posixDst.view())) + { + return gp::makeUnexpected(FileError::AlreadyExists); + } + + if (::rename(posixSrc.cString(), posixDst.cString()) != 0) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + return true; +} + +gp::Expected FileSystem::copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + if (sourcePath.isEmpty() || destinationPath.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (Paths::equals(sourcePath, destinationPath)) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected srcOpen = openRead(sourcePath); + if (!srcOpen.hasValue()) + { + return gp::makeUnexpected(srcOpen.error()); + } + + const FileOpenMode dstMode = overwrite ? FileOpenMode::CreateAlways : FileOpenMode::CreateNew; + gp::Expected dstOpen = + open(destinationPath, FileAccessMode::Write, dstMode, FileShareMode::None); + if (!dstOpen.hasValue()) + { + return gp::makeUnexpected(dstOpen.error()); + } + + FileHandle& srcHandle = srcOpen.value(); + FileHandle& dstHandle = dstOpen.value(); + + gp::Byte chunkBuf[kFileCopyChunkSize]{}; + while (true) + { + const gp::Expected readRes = srcHandle.read(chunkBuf, kFileCopyChunkSize); + if (!readRes.hasValue()) + { + return gp::makeUnexpected(readRes.error()); + } + const gp::USize bytesRead = readRes.value(); + if (bytesRead == 0u) + { + break; + } + + const gp::Expected writeRes = dstHandle.write(chunkBuf, bytesRead); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != bytesRead) + { + return gp::makeUnexpected(FileError::DiskFull); + } + } + + return true; +} + +gp::Expected FileSystem::iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + if (visitor == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + PathBuffer baseDir{}; + if (!detail::toPosixPath(directoryPath, baseDir, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + DIR* const dirStream = ::opendir(baseDir.cString()); + if (dirStream == nullptr) + { + return gp::makeUnexpected(detail::mapPosixErrno(errno)); + } + + while (true) + { + errno = 0; + const struct dirent* const ent = ::readdir(dirStream); + if (ent == nullptr) + { + if (errno != 0) + { + const int err = errno; + ::closedir(dirStream); + return gp::makeUnexpected(detail::mapPosixErrno(err)); + } + break; + } + + const char* const rawName = ent->d_name; + if (rawName[0] == '.' && (rawName[1] == '\0' || (rawName[1] == '.' && rawName[2] == '\0'))) + { + continue; + } + + const gp::StringView leafName(rawName); + const PathBuffer fullEntryPath = Paths::combine(baseDir.view(), leafName); + const gp::Expected entryStats = getStats(fullEntryPath.view()); + if (!entryStats.hasValue()) + { + continue; + } + + DirectoryEntry entry{}; + entry.path = fullEntryPath.view(); + entry.name = Paths::getCleanFilename(entry.path); + entry.stats = entryStats.value(); + entry.depth = 0u; + + const DirectoryVisitControl ctrl = visitor(entry, userData); + if (ctrl == DirectoryVisitControl::Stop) + { + break; + } + } + + ::closedir(dirStream); + return true; +} + +gp::Expected FileSystem::iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + bool stopped = false; + return iterateDirectoryRecursiveImpl(directoryPath, visitor, userData, 0u, stopped); +} + +gp::Expected + FileSystem::readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept +{ + if (bufferCapacity > 0u && outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openRead(path); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + return openRes.value().read(outBuffer, bufferCapacity); +} + +gp::Expected + FileSystem::writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openWrite(path, false, false); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + if (sizeInBytes == 0u) + { + return true; + } + + const gp::Expected writeRes = openRes.value().write(data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != sizeInBytes) + { + return gp::makeUnexpected(FileError::DiskFull); + } + + return true; +} + +gp::Expected FileSystem::writeAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openWrite(path, true, false); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + if (sizeInBytes == 0u) + { + return true; + } + + const gp::Expected writeRes = openRes.value().write(data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != sizeInBytes) + { + return gp::makeUnexpected(FileError::DiskFull); + } + + return true; +} + +gp::Expected FileSystem::appendAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return appendAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + return writeAtomicImpl(path, data, sizeInBytes); +} + +gp::Expected FileSystem::writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAtomic(path, text.data(), text.size()); +} + +} // namespace gp::platform::unix diff --git a/source/runtime/core/private/platforms/windows/system/WindowsFileSystem.cpp b/source/runtime/core/private/platforms/windows/system/WindowsFileSystem.cpp new file mode 100644 index 00000000..8741ae3a --- /dev/null +++ b/source/runtime/core/private/platforms/windows/system/WindowsFileSystem.cpp @@ -0,0 +1,1088 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/windows/system/WindowsFileSystem.hpp" +#include "platforms/base/system/Paths.hpp" +#include "platforms/windows/WindowsHeaderWrapper.hpp" // IWYU pragma: keep + +namespace gp::platform::windows::detail +{ + +/// @brief Maximum UTF-16 `wchar_t` stack buffer capacity for Win32 filesystem calls. +constexpr gp::USize kWin32WidePathCapacity = kMaxPathLength + 16u; + +/// @brief Difference between the Windows `FILETIME` Epoch (`1601-01-01T00:00:00Z`) and Unix Epoch +/// (`1970-01-01T00:00:00Z`) +/// measured in 100-nanosecond intervals. +constexpr gp::UInt64 kWin32FileTimeToUnixEpochTicks = 116444736000000000ULL; + +/// @brief Maps a Win32 `GetLastError()` code to the canonical engine `gp::platform::FileError` enumeration. +/// @param[in] win32Error Raw `DWORD` error code returned by `::GetLastError()`. +/// @return Mapped `FileError` enum value. +[[nodiscard]] static FileError mapWin32Error(const DWORD win32Error) noexcept +{ + switch (win32Error) + { + case ERROR_SUCCESS: + return FileError::None; + case ERROR_FILE_NOT_FOUND: + case ERROR_PATH_NOT_FOUND: + case ERROR_INVALID_DRIVE: + case ERROR_BAD_NETPATH: + case ERROR_BAD_NET_NAME: + return FileError::NotFound; + case ERROR_FILE_EXISTS: + case ERROR_ALREADY_EXISTS: + return FileError::AlreadyExists; + case ERROR_ACCESS_DENIED: + case ERROR_PRIVILEGE_NOT_HELD: + case ERROR_CURRENT_DIRECTORY: + return FileError::AccessDenied; + case ERROR_SHARING_VIOLATION: + case ERROR_LOCK_VIOLATION: + return FileError::SharingViolation; + case ERROR_WRITE_PROTECT: + return FileError::ReadOnlyFileSystem; + case ERROR_INVALID_NAME: + case ERROR_FILENAME_EXCED_RANGE: + case ERROR_BAD_PATHNAME: + case ERROR_DIRECTORY: + return FileError::InvalidPath; + case ERROR_INVALID_HANDLE: + return FileError::InvalidHandle; + case ERROR_INVALID_PARAMETER: + case ERROR_NEGATIVE_SEEK: + return FileError::InvalidArgument; + case ERROR_DIR_NOT_EMPTY: + return FileError::DirectoryNotEmpty; + case ERROR_DISK_FULL: + case ERROR_HANDLE_DISK_FULL: + return FileError::DiskFull; + case ERROR_TOO_MANY_OPEN_FILES: + return FileError::TooManyOpenFiles; + case ERROR_NOT_SAME_DEVICE: + return FileError::CrossDeviceLink; + default: + return FileError::IoFailure; + } +} + +/// @brief Converts a UTF-8 `gp::StringView` path into a null-terminated Win32 UTF-16 `wchar_t` buffer on the stack. +/// @param[in] utf8Path Input UTF-8 path view. +/// @param[out] outWideBuf Destination stack buffer of capacity `kWin32WidePathCapacity`. +/// @param[in] trimTrailingSlash If true, removes redundant trailing slashes prior to conversion. +/// @return True if conversion succeeded and produced a valid non-empty UTF-16 path, false otherwise. +[[nodiscard]] static bool toWin32WidePath( + const gp::StringView utf8Path, wchar_t (&outWideBuf)[kWin32WidePathCapacity], const bool trimTrailingSlash = false +) noexcept +{ + outWideBuf[0] = L'\0'; + if (utf8Path.isEmpty() || utf8Path.size() > kMaxPathLength) + { + return false; + } + + PathBuffer platformPath(utf8Path); + if (trimTrailingSlash) + { + Paths::normalizeDirectoryName(platformPath); + } + Paths::makePlatformFilename(platformPath); + if (platformPath.isEmpty()) + { + return false; + } + + const int wideLen = ::MultiByteToWideChar( + CP_UTF8, + MB_ERR_INVALID_CHARS, + platformPath.cString(), + static_cast(platformPath.size()), + outWideBuf, + static_cast(kWin32WidePathCapacity - 1u) + ); + + if (wideLen <= 0 || static_cast(wideLen) >= kWin32WidePathCapacity) + { + outWideBuf[0] = L'\0'; + return false; + } + + outWideBuf[wideLen] = L'\0'; + return true; +} + +/// @brief Converts a Win32 `FILETIME` (100-ns intervals since 1601-01-01) into a `gp::time::Timestamp` (Unix Epoch ns). +/// @param[in] ft Win32 `FILETIME` structure. +/// @return Normalized `gp::time::Timestamp` in nanoseconds since 1970-01-01 UTC. +[[nodiscard]] static gp::time::Timestamp fileTimeToTimestamp(const FILETIME& ft) noexcept +{ + ULARGE_INTEGER uli{}; + uli.LowPart = ft.dwLowDateTime; + uli.HighPart = ft.dwHighDateTime; + + if (uli.QuadPart <= kWin32FileTimeToUnixEpochTicks) + { + return gp::time::Timestamp(0ULL); + } + + const gp::UInt64 unixTicks100ns = uli.QuadPart - kWin32FileTimeToUnixEpochTicks; + return gp::time::Timestamp(unixTicks100ns * 100ULL); +} + +/// @brief Populates a `FileStats` structure from Win32 file attributes, sizes, and `FILETIME` timestamps. +/// @param[in] dwFileAttributes Win32 `FILE_ATTRIBUTE_*` bitmask. +/// @param[in] nFileSizeHigh High 32 bits of file size. +/// @param[in] nFileSizeLow Low 32 bits of file size. +/// @param[in] ftCreationTime Win32 creation timestamp. +/// @param[in] ftLastWriteTime Win32 modification timestamp. +/// @param[in] ftLastAccessTime Win32 last-access timestamp. +/// @return Populated `FileStats` snapshot. +[[nodiscard]] static FileStats buildStatsFromWin32Data( + const DWORD dwFileAttributes, + const DWORD nFileSizeHigh, + const DWORD nFileSizeLow, + const FILETIME& ftCreationTime, + const FILETIME& ftLastWriteTime, + const FILETIME& ftLastAccessTime +) noexcept +{ + FileStats stats{}; + const bool isDir = (dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) != 0u; + stats.size = + isDir ? 0ULL : ((static_cast(nFileSizeHigh) << 32u) | static_cast(nFileSizeLow)); + stats.creationTime = fileTimeToTimestamp(ftCreationTime); + stats.lastWriteTime = fileTimeToTimestamp(ftLastWriteTime); + stats.lastAccessTime = fileTimeToTimestamp(ftLastAccessTime); + + FileAttributeFlags flags = isDir ? FileAttributeFlags::Directory : FileAttributeFlags::RegularFile; + if ((dwFileAttributes & FILE_ATTRIBUTE_READONLY) != 0u) + { + flags = flags | FileAttributeFlags::ReadOnly; + } + if ((dwFileAttributes & FILE_ATTRIBUTE_HIDDEN) != 0u) + { + flags = flags | FileAttributeFlags::Hidden; + } + if ((dwFileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0u) + { + flags = flags | FileAttributeFlags::SymbolicLink; + } + + stats.attributes = flags; + return stats; +} + +} // namespace gp::platform::windows::detail + +namespace gp::platform +{ + +gp::Expected FileHandle::close() noexcept +{ + if (!isValid()) + { + return true; + } + + const HANDLE rawHandle = static_cast(m_descriptor); + m_descriptor = kInvalidNativeFileDescriptor; + + if (::CloseHandle(rawHandle) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + return true; +} + +gp::Expected FileHandle::read(void* const outBuffer, const gp::USize bytesToRead) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToRead == 0u) + { + return 0u; + } + if (outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const HANDLE rawHandle = static_cast(m_descriptor); + gp::Byte* dst = static_cast(outBuffer); + gp::USize totalRead = 0u; + + while (totalRead < bytesToRead) + { + const gp::USize remaining = bytesToRead - totalRead; + const DWORD chunkToRead = + (remaining > static_cast(0x7FFFFFFFu)) ? 0x7FFFFFFFu : static_cast(remaining); + + DWORD chunkRead = 0u; + if (::ReadFile(rawHandle, dst + totalRead, chunkToRead, &chunkRead, nullptr) == 0) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_HANDLE_EOF) + { + break; + } + return gp::makeUnexpected(windows::detail::mapWin32Error(err)); + } + + if (chunkRead == 0u) + { + break; + } + totalRead += static_cast(chunkRead); + } + + return totalRead; +} + +gp::Expected FileHandle::write(const void* const buffer, const gp::USize bytesToWrite) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToWrite == 0u) + { + return 0u; + } + if (buffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const HANDLE rawHandle = static_cast(m_descriptor); + const gp::Byte* src = static_cast(buffer); + gp::USize totalWritten = 0u; + + while (totalWritten < bytesToWrite) + { + const gp::USize remaining = bytesToWrite - totalWritten; + const DWORD chunkToWrite = + (remaining > static_cast(0x7FFFFFFFu)) ? 0x7FFFFFFFu : static_cast(remaining); + + DWORD chunkWritten = 0u; + if (::WriteFile(rawHandle, src + totalWritten, chunkToWrite, &chunkWritten, nullptr) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + if (chunkWritten == 0u) + { + break; + } + totalWritten += static_cast(chunkWritten); + } + + return totalWritten; +} + +gp::Expected + FileHandle::readAt(const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead) const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToRead == 0u) + { + return 0u; + } + if (outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const HANDLE rawHandle = static_cast(m_descriptor); + gp::Byte* dst = static_cast(outBuffer); + gp::USize totalRead = 0u; + + // Pedagogical note: Passing a stack-allocated OVERLAPPED struct with an explicit 64-bit Offset/OffsetHigh to + // synchronous ReadFile tells the NT I/O Manager to read directly at the requested byte offset without consulting + // the shared FILE_OBJECT::CurrentByteOffset, allowing lock-free concurrent reads across JobSystem fibers. + while (totalRead < bytesToRead) + { + const gp::UInt64 currentOffset = offset + static_cast(totalRead); + const gp::USize remaining = bytesToRead - totalRead; + const DWORD chunkToRead = + (remaining > static_cast(0x7FFFFFFFu)) ? 0x7FFFFFFFu : static_cast(remaining); + + OVERLAPPED overlapped{}; + overlapped.Offset = static_cast(currentOffset & 0xFFFFFFFFULL); + overlapped.OffsetHigh = static_cast(currentOffset >> 32u); + + DWORD chunkRead = 0u; + if (::ReadFile(rawHandle, dst + totalRead, chunkToRead, &chunkRead, &overlapped) == 0) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_HANDLE_EOF) + { + break; + } + return gp::makeUnexpected(windows::detail::mapWin32Error(err)); + } + + if (chunkRead == 0u) + { + break; + } + totalRead += static_cast(chunkRead); + } + + return totalRead; +} + +gp::Expected + FileHandle::writeAt(const gp::UInt64 offset, const void* const buffer, const gp::USize bytesToWrite) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + if (bytesToWrite == 0u) + { + return 0u; + } + if (buffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const HANDLE rawHandle = static_cast(m_descriptor); + const gp::Byte* src = static_cast(buffer); + gp::USize totalWritten = 0u; + + while (totalWritten < bytesToWrite) + { + const gp::UInt64 currentOffset = offset + static_cast(totalWritten); + const gp::USize remaining = bytesToWrite - totalWritten; + const DWORD chunkToWrite = + (remaining > static_cast(0x7FFFFFFFu)) ? 0x7FFFFFFFu : static_cast(remaining); + + OVERLAPPED overlapped{}; + overlapped.Offset = static_cast(currentOffset & 0xFFFFFFFFULL); + overlapped.OffsetHigh = static_cast(currentOffset >> 32u); + + DWORD chunkWritten = 0u; + if (::WriteFile(rawHandle, src + totalWritten, chunkToWrite, &chunkWritten, &overlapped) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + if (chunkWritten == 0u) + { + break; + } + totalWritten += static_cast(chunkWritten); + } + + return totalWritten; +} + +gp::Expected FileHandle::seek(const gp::Int64 offset, const FileSeekOrigin origin) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + DWORD moveMethod = FILE_BEGIN; + switch (origin) + { + case FileSeekOrigin::Begin: + moveMethod = FILE_BEGIN; + break; + case FileSeekOrigin::Current: + moveMethod = FILE_CURRENT; + break; + case FileSeekOrigin::End: + moveMethod = FILE_END; + break; + default: + return gp::makeUnexpected(FileError::InvalidArgument); + } + + LARGE_INTEGER distance{}; + distance.QuadPart = offset; + LARGE_INTEGER newPos{}; + + if (::SetFilePointerEx(static_cast(m_descriptor), distance, &newPos, moveMethod) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + return static_cast(newPos.QuadPart); +} + +gp::Expected FileHandle::tell() const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + const LARGE_INTEGER zero{}; + LARGE_INTEGER currentPos{}; + if (::SetFilePointerEx(static_cast(m_descriptor), zero, ¤tPos, FILE_CURRENT) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + return static_cast(currentPos.QuadPart); +} + +gp::Expected FileHandle::size() const noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + LARGE_INTEGER fileSize{}; + if (::GetFileSizeEx(static_cast(m_descriptor), &fileSize) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + return static_cast(fileSize.QuadPart); +} + +gp::Expected FileHandle::flush() noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + if (::FlushFileBuffers(static_cast(m_descriptor)) == 0) + { + return gp::makeUnexpected(windows::detail::mapWin32Error(::GetLastError())); + } + + return true; +} + +gp::Expected FileHandle::truncate(const gp::UInt64 newSize) noexcept +{ + if (!isValid()) + { + return gp::makeUnexpected(FileError::InvalidHandle); + } + + const gp::Expected savedPos = tell(); + if (!savedPos.hasValue()) + { + return gp::makeUnexpected(savedPos.error()); + } + + const gp::Expected seekRes = seek(static_cast(newSize), FileSeekOrigin::Begin); + if (!seekRes.hasValue()) + { + return gp::makeUnexpected(seekRes.error()); + } + + if (::SetEndOfFile(static_cast(m_descriptor)) == 0) + { + const DWORD err = ::GetLastError(); + (void)seek(static_cast(savedPos.value()), FileSeekOrigin::Begin); + return gp::makeUnexpected(windows::detail::mapWin32Error(err)); + } + + const gp::UInt64 restoredPos = (savedPos.value() <= newSize) ? savedPos.value() : newSize; + (void)seek(static_cast(restoredPos), FileSeekOrigin::Begin); + return true; +} + +} // namespace gp::platform + +namespace gp::platform::windows +{ + +gp::Expected FileSystem::open( + const gp::StringView path, const FileAccessMode access, const FileOpenMode openMode, const FileShareMode shareMode +) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + DWORD desiredAccess = 0u; + if (gp::enums::hasAllFlags(access, FileAccessMode::Read)) + { + desiredAccess |= GENERIC_READ; + } + if (gp::enums::hasAllFlags(access, FileAccessMode::Write)) + { + // For Append mode without read access, Win32 FILE_APPEND_DATA guarantees kernel-atomic end-of-file writes + // matching POSIX O_APPEND even when multiple handles append concurrently. + if (openMode == FileOpenMode::Append && !gp::enums::hasAllFlags(access, FileAccessMode::Read)) + { + desiredAccess |= FILE_APPEND_DATA; + } + else + { + desiredAccess |= GENERIC_WRITE; + } + } + if (desiredAccess == 0u) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + DWORD winShare = 0u; + if (gp::enums::hasAllFlags(shareMode, FileShareMode::Read)) + { + winShare |= FILE_SHARE_READ; + } + if (gp::enums::hasAllFlags(shareMode, FileShareMode::Write)) + { + winShare |= FILE_SHARE_WRITE; + } + if (gp::enums::hasAllFlags(shareMode, FileShareMode::Delete)) + { + winShare |= FILE_SHARE_DELETE; + } + + DWORD creationDisposition = OPEN_EXISTING; + switch (openMode) + { + case FileOpenMode::OpenExisting: + creationDisposition = OPEN_EXISTING; + break; + case FileOpenMode::CreateAlways: + creationDisposition = CREATE_ALWAYS; + break; + case FileOpenMode::CreateNew: + creationDisposition = CREATE_NEW; + break; + case FileOpenMode::OpenAlways: + case FileOpenMode::Append: + creationDisposition = OPEN_ALWAYS; + break; + default: + return gp::makeUnexpected(FileError::InvalidArgument); + } + + const HANDLE rawHandle = + ::CreateFileW(widePath, desiredAccess, winShare, nullptr, creationDisposition, FILE_ATTRIBUTE_NORMAL, nullptr); + + if (rawHandle == INVALID_HANDLE_VALUE) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_ACCESS_DENIED) + { + const DWORD attrs = ::GetFileAttributesW(widePath); + if (attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) != 0u) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + FileHandle handle(static_cast(rawHandle)); + if (openMode == FileOpenMode::Append && gp::enums::hasAllFlags(access, FileAccessMode::Read)) + { + const gp::Expected seekEnd = handle.seek(0, FileSeekOrigin::End); + if (!seekEnd.hasValue()) + { + return gp::makeUnexpected(seekEnd.error()); + } + } + + return handle; +} + +gp::Expected + FileSystem::openRead(const gp::StringView path, const FileShareMode shareMode) noexcept +{ + return open(path, FileAccessMode::Read, FileOpenMode::OpenExisting, shareMode); +} + +gp::Expected FileSystem::openWrite( + const gp::StringView path, const bool append, const bool allowRead, const FileShareMode shareMode +) noexcept +{ + const FileAccessMode access = allowRead ? FileAccessMode::ReadWrite : FileAccessMode::Write; + const FileOpenMode mode = append ? FileOpenMode::Append : FileOpenMode::CreateAlways; + return open(path, access, mode, shareMode); +} + +gp::Expected FileSystem::getStats(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + WIN32_FILE_ATTRIBUTE_DATA attrData{}; + if (::GetFileAttributesExW(widePath, GetFileExInfoStandard, &attrData) == 0) + { + return gp::makeUnexpected(detail::mapWin32Error(::GetLastError())); + } + + return detail::buildStatsFromWin32Data( + attrData.dwFileAttributes, + attrData.nFileSizeHigh, + attrData.nFileSizeLow, + attrData.ftCreationTime, + attrData.ftLastWriteTime, + attrData.ftLastAccessTime + ); +} + +bool FileSystem::exists(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return false; + } + + return ::GetFileAttributesW(widePath) != INVALID_FILE_ATTRIBUTES; +} + +bool FileSystem::isFile(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return false; + } + + const DWORD attrs = ::GetFileAttributesW(widePath); + return attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) == 0u; +} + +bool FileSystem::isDirectory(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return false; + } + + const DWORD attrs = ::GetFileAttributesW(widePath); + return attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) != 0u; +} + +bool FileSystem::isReadOnly(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return false; + } + + const DWORD attrs = ::GetFileAttributesW(widePath); + return attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_READONLY) != 0u; +} + +gp::Expected FileSystem::setReadOnly(const gp::StringView path, const bool readOnly) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + DWORD attrs = ::GetFileAttributesW(widePath); + if (attrs == INVALID_FILE_ATTRIBUTES) + { + return gp::makeUnexpected(detail::mapWin32Error(::GetLastError())); + } + + if (readOnly) + { + attrs |= FILE_ATTRIBUTE_READONLY; + } + else + { + attrs &= ~static_cast(FILE_ATTRIBUTE_READONLY); + if (attrs == 0u) + { + attrs = FILE_ATTRIBUTE_NORMAL; + } + } + + if (::SetFileAttributesW(widePath, attrs) == 0) + { + return gp::makeUnexpected(detail::mapWin32Error(::GetLastError())); + } + + return true; +} + +gp::Expected FileSystem::fileSize(const gp::StringView path) noexcept +{ + const gp::Expected stats = getStats(path); + if (!stats.hasValue()) + { + return gp::makeUnexpected(stats.error()); + } + if (stats.value().isDirectory()) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + return stats.value().size; +} + +gp::Expected FileSystem::createDirectory(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (::CreateDirectoryW(widePath, nullptr) == 0) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_ALREADY_EXISTS) + { + const DWORD attrs = ::GetFileAttributesW(widePath); + if (attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) != 0u) + { + return true; + } + return gp::makeUnexpected(FileError::AlreadyExists); + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + return true; +} + +gp::Expected FileSystem::createDirectoryTree(const gp::StringView path) noexcept +{ + return createDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::removeFile(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (::DeleteFileW(widePath) == 0) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_ACCESS_DENIED) + { + const DWORD attrs = ::GetFileAttributesW(widePath); + if (attrs != INVALID_FILE_ATTRIBUTES && (attrs & FILE_ATTRIBUTE_DIRECTORY) != 0u) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + return true; +} + +gp::Expected FileSystem::removeDirectory(const gp::StringView path) noexcept +{ + wchar_t widePath[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(path, widePath, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + const DWORD attrs = ::GetFileAttributesW(widePath); + if (attrs == INVALID_FILE_ATTRIBUTES) + { + return gp::makeUnexpected(detail::mapWin32Error(::GetLastError())); + } + if ((attrs & FILE_ATTRIBUTE_DIRECTORY) == 0u) + { + return gp::makeUnexpected(FileError::NotDirectory); + } + + if (::RemoveDirectoryW(widePath) == 0) + { + return gp::makeUnexpected(detail::mapWin32Error(::GetLastError())); + } + + return true; +} + +gp::Expected FileSystem::removeDirectoryTree(const gp::StringView path) noexcept +{ + return removeDirectoryTreeImpl(path); +} + +gp::Expected FileSystem::move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + wchar_t wideSrc[detail::kWin32WidePathCapacity]{}; + wchar_t wideDst[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(sourcePath, wideSrc, true) || !detail::toWin32WidePath(destinationPath, wideDst, true)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + const DWORD flags = overwrite ? (MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) : 0u; + if (::MoveFileExW(wideSrc, wideDst, flags) == 0) + { + const DWORD err = ::GetLastError(); + if (!overwrite && err == ERROR_ALREADY_EXISTS) + { + return gp::makeUnexpected(FileError::AlreadyExists); + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + return true; +} + +gp::Expected FileSystem::copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite +) noexcept +{ + wchar_t wideSrc[detail::kWin32WidePathCapacity]{}; + wchar_t wideDst[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(sourcePath, wideSrc, false) || + !detail::toWin32WidePath(destinationPath, wideDst, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (Paths::equals(sourcePath, destinationPath)) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + if (::CopyFileW(wideSrc, wideDst, overwrite ? FALSE : TRUE) == 0) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_ACCESS_DENIED) + { + const DWORD srcAttrs = ::GetFileAttributesW(wideSrc); + if (srcAttrs != INVALID_FILE_ATTRIBUTES && (srcAttrs & FILE_ATTRIBUTE_DIRECTORY) != 0u) + { + return gp::makeUnexpected(FileError::IsDirectory); + } + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + return true; +} + +gp::Expected FileSystem::iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + if (visitor == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + if (directoryPath.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + const gp::Expected dirStats = getStats(directoryPath); + if (!dirStats.hasValue()) + { + return gp::makeUnexpected(dirStats.error()); + } + if (!dirStats.value().isDirectory()) + { + return gp::makeUnexpected(FileError::NotDirectory); + } + + PathBuffer baseDir(directoryPath); + Paths::normalizeDirectoryName(baseDir); + + PathBuffer searchPattern = Paths::combine(baseDir.view(), "*"); + wchar_t widePattern[detail::kWin32WidePathCapacity]{}; + if (!detail::toWin32WidePath(searchPattern.view(), widePattern, false)) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + WIN32_FIND_DATAW findData{}; + const HANDLE findHandle = ::FindFirstFileExW( + widePattern, FindExInfoBasic, &findData, FindExSearchNameMatch, nullptr, FIND_FIRST_EX_LARGE_FETCH + ); + + if (findHandle == INVALID_HANDLE_VALUE) + { + const DWORD err = ::GetLastError(); + if (err == ERROR_FILE_NOT_FOUND) + { + return true; + } + return gp::makeUnexpected(detail::mapWin32Error(err)); + } + + do + { + const wchar_t* const wName = findData.cFileName; + if (wName[0] == L'.' && (wName[1] == L'\0' || (wName[1] == L'.' && wName[2] == L'\0'))) + { + continue; + } + + char utf8Name[kMaxPathLength + 1u]{}; + const int utf8Len = ::WideCharToMultiByte( + CP_UTF8, 0u, wName, -1, utf8Name, static_cast(kMaxPathLength + 1u), nullptr, nullptr + ); + if (utf8Len <= 1) + { + continue; + } + + const gp::StringView leafName(utf8Name, static_cast(utf8Len - 1)); + const PathBuffer fullEntryPath = Paths::combine(baseDir.view(), leafName); + + DirectoryEntry entry{}; + entry.path = fullEntryPath.view(); + entry.name = Paths::getCleanFilename(entry.path); + entry.stats = detail::buildStatsFromWin32Data( + findData.dwFileAttributes, + findData.nFileSizeHigh, + findData.nFileSizeLow, + findData.ftCreationTime, + findData.ftLastWriteTime, + findData.ftLastAccessTime + ); + entry.depth = 0u; + + const DirectoryVisitControl ctrl = visitor(entry, userData); + if (ctrl == DirectoryVisitControl::Stop) + { + break; + } + } + while (::FindNextFileW(findHandle, &findData) != 0); + + ::FindClose(findHandle); + return true; +} + +gp::Expected FileSystem::iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData +) noexcept +{ + bool stopped = false; + return iterateDirectoryRecursiveImpl(directoryPath, visitor, userData, 0u, stopped); +} + +gp::Expected + FileSystem::readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept +{ + if (bufferCapacity > 0u && outBuffer == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openRead(path); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + return openRes.value().read(outBuffer, bufferCapacity); +} + +gp::Expected + FileSystem::writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openWrite(path, false, false); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + if (sizeInBytes == 0u) + { + return true; + } + + const gp::Expected writeRes = openRes.value().write(data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != sizeInBytes) + { + return gp::makeUnexpected(FileError::DiskFull); + } + + return true; +} + +gp::Expected FileSystem::writeAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + gp::Expected openRes = openWrite(path, true, false); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + if (sizeInBytes == 0u) + { + return true; + } + + const gp::Expected writeRes = openRes.value().write(data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != sizeInBytes) + { + return gp::makeUnexpected(FileError::DiskFull); + } + + return true; +} + +gp::Expected FileSystem::appendAllText(const gp::StringView path, const gp::StringView text) noexcept +{ + return appendAllBytes(path, text.data(), text.size()); +} + +gp::Expected + FileSystem::writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept +{ + return writeAtomicImpl(path, data, sizeInBytes); +} + +gp::Expected FileSystem::writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept +{ + return writeAtomic(path, text.data(), text.size()); +} + +} // namespace gp::platform::windows diff --git a/source/runtime/core/private/vfs/MemoryMountBackend.cpp b/source/runtime/core/private/vfs/MemoryMountBackend.cpp new file mode 100644 index 00000000..254daef3 --- /dev/null +++ b/source/runtime/core/private/vfs/MemoryMountBackend.cpp @@ -0,0 +1,709 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "vfs/MemoryMountBackend.hpp" +#include "platforms/base/system/Paths.hpp" +#include "platforms/base/system/Time.hpp" +#include "threading/sync/SharedLock.hpp" +#include "threading/sync/UniqueLock.hpp" +#include + +namespace gp::vfs +{ + +MemoryMountBackend::MemoryMountBackend() noexcept +{ + clear(); +} + +MemoryMountBackend::MemoryMountBackend(const gp::StringView identifier) noexcept +{ + if (!identifier.isEmpty()) + { + m_identifier.assign(identifier); + } + clear(); +} + +void MemoryMountBackend::clear() noexcept +{ + const gp::thread::UniqueLock lock(m_mutex); + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + m_nodes[i].relativePath.clear(); + m_nodes[i].content.reset(); + m_nodes[i].stats = {}; + m_nodes[i].active = false; + } + + const gp::time::Timestamp nowTs(gp::platform::Time::utcTimestampMicroseconds() * 1000ULL); + m_nodes[0].relativePath.clear(); + m_nodes[0].stats.size = 0ULL; + m_nodes[0].stats.creationTime = nowTs; + m_nodes[0].stats.lastWriteTime = nowTs; + m_nodes[0].stats.lastAccessTime = nowTs; + m_nodes[0].stats.attributes = gp::platform::FileAttributeFlags::Directory; + m_nodes[0].active = true; +} + +VfsError MemoryMountBackend::normalizeRelativeKey( + const gp::StringView rawRelativePath, gp::PathBuffer& outNormalized +) noexcept +{ + outNormalized.clear(); + if (rawRelativePath.isEmpty()) + { + return VfsError::None; + } + if (rawRelativePath.size() > gp::platform::kMaxPathLength) + { + return VfsError::InvalidUri; + } + + gp::PathBuffer temp(rawRelativePath); + gp::platform::Paths::normalizeDirectoryName(temp); + if (!gp::platform::Paths::collapseRelativeDirectories(temp)) + { + return VfsError::SandboxEscapeViolation; + } + + gp::StringView view = temp.view(); + while (!view.isEmpty() && gp::platform::Paths::isSeparator(view.front())) + { + view = view.substr(1u); + } + while (!view.isEmpty() && gp::platform::Paths::isSeparator(view.back())) + { + view = view.substr(0u, view.size() - 1u); + } + + if (view == ".." || view.startsWith("../")) + { + return VfsError::SandboxEscapeViolation; + } + if (view == ".") + { + return VfsError::None; + } + + outNormalized.assign(view); + return VfsError::None; +} + +gp::USize MemoryMountBackend::findNodeIndexUnlocked(const gp::StringView normalizedKey) const noexcept +{ + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (m_nodes[i].active && m_nodes[i].relativePath.view() == normalizedKey) + { + return i; + } + } + return kMaxMemoryMountNodes; +} + +gp::USize MemoryMountBackend::allocateNodeSlotUnlocked() noexcept +{ + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (!m_nodes[i].active) + { + return i; + } + } + return kMaxMemoryMountNodes; +} + +gp::Expected MemoryMountBackend::createDirectoryUnlocked(const gp::StringView normalizedKey) noexcept +{ + if (normalizedKey.isEmpty()) + { + return true; + } + + const gp::USize existingIdx = findNodeIndexUnlocked(normalizedKey); + if (existingIdx < kMaxMemoryMountNodes) + { + if (m_nodes[existingIdx].stats.isDirectory()) + { + return true; + } + return gp::makeUnexpected(VfsError::AlreadyExists); + } + + const gp::StringView parentDir = gp::platform::Paths::getPath(normalizedKey); + const gp::USize parentIdx = findNodeIndexUnlocked(parentDir); + if (parentIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (!m_nodes[parentIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + + const gp::USize slot = allocateNodeSlotUnlocked(); + if (slot >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::MountTableFull); + } + + const gp::time::Timestamp nowTs(gp::platform::Time::utcTimestampMicroseconds() * 1000ULL); + m_nodes[slot].relativePath.assign(normalizedKey); + m_nodes[slot].content.clear(); + m_nodes[slot].stats.size = 0ULL; + m_nodes[slot].stats.creationTime = nowTs; + m_nodes[slot].stats.lastWriteTime = nowTs; + m_nodes[slot].stats.lastAccessTime = nowTs; + m_nodes[slot].stats.attributes = gp::platform::FileAttributeFlags::Directory; + m_nodes[slot].active = true; + return true; +} + +gp::StringView MemoryMountBackend::rootPath() const noexcept +{ + return m_identifier.view(); +} + +bool MemoryMountBackend::isPhysical() const noexcept +{ + return false; +} + +gp::Expected + MemoryMountBackend::resolvePhysicalPath([[maybe_unused]] const gp::StringView relativePath) const noexcept +{ + return gp::makeUnexpected(VfsError::NotSupported); +} + +bool MemoryMountBackend::exists(const gp::StringView relativePath) const noexcept +{ + gp::PathBuffer key{}; + if (normalizeRelativeKey(relativePath, key) != VfsError::None) + { + return false; + } + + const gp::thread::SharedLock lock(m_mutex); + return findNodeIndexUnlocked(key.view()) < kMaxMemoryMountNodes; +} + +gp::Expected + MemoryMountBackend::getStats(const gp::StringView relativePath) const noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + + const gp::thread::SharedLock lock(m_mutex); + const gp::USize idx = findNodeIndexUnlocked(key.view()); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + return m_nodes[idx].stats; +} + +gp::Expected MemoryMountBackend::openFileHandle( + [[maybe_unused]] const gp::StringView relativePath, + [[maybe_unused]] const gp::platform::FileAccessMode access, + [[maybe_unused]] const gp::platform::FileOpenMode openMode, + [[maybe_unused]] const gp::platform::FileShareMode shareMode +) noexcept +{ + return gp::makeUnexpected(VfsError::NotSupported); +} + +gp::Expected MemoryMountBackend::readBytesAt( + const gp::StringView relativePath, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead +) const noexcept +{ + if (bytesToRead > 0u && outBuffer == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + + const gp::thread::SharedLock lock(m_mutex); + const gp::USize idx = findNodeIndexUnlocked(key.view()); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (m_nodes[idx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::String& content = m_nodes[idx].content; + if (offset >= static_cast(content.size()) || bytesToRead == 0u) + { + return 0u; + } + + const gp::USize startOffset = static_cast(offset); + const gp::USize available = content.size() - startOffset; + const gp::USize toCopy = (bytesToRead < available) ? bytesToRead : available; + std::memcpy(outBuffer, content.data() + startOffset, toCopy); + return toCopy; +} + +gp::Expected MemoryMountBackend::writeBytes( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes, const bool append +) noexcept +{ + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + if (key.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::StringView parentDir = gp::platform::Paths::getPath(key.view()); + const gp::USize parentIdx = findNodeIndexUnlocked(parentDir); + if (parentIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (!m_nodes[parentIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + + gp::USize idx = findNodeIndexUnlocked(key.view()); + const gp::time::Timestamp nowTs(gp::platform::Time::utcTimestampMicroseconds() * 1000ULL); + + if (idx < kMaxMemoryMountNodes) + { + if (m_nodes[idx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + if (m_nodes[idx].stats.isReadOnly()) + { + return gp::makeUnexpected(VfsError::AccessDenied); + } + if (!append) + { + m_nodes[idx].content.clear(); + } + } + else + { + idx = allocateNodeSlotUnlocked(); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::MountTableFull); + } + m_nodes[idx].relativePath = key; + m_nodes[idx].content.clear(); + m_nodes[idx].stats.creationTime = nowTs; + m_nodes[idx].stats.attributes = gp::platform::FileAttributeFlags::RegularFile; + m_nodes[idx].active = true; + } + + if (sizeInBytes > 0u) + { + m_nodes[idx].content.append(static_cast(data), sizeInBytes); + } + m_nodes[idx].stats.size = static_cast(m_nodes[idx].content.size()); + m_nodes[idx].stats.lastWriteTime = nowTs; + m_nodes[idx].stats.lastAccessTime = nowTs; + return true; +} + +gp::Expected MemoryMountBackend::writeAtomic( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes +) noexcept +{ + return writeBytes(relativePath, data, sizeInBytes, false); +} + +gp::Expected MemoryMountBackend::createDirectory(const gp::StringView relativePath) noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + + const gp::thread::UniqueLock lock(m_mutex); + return createDirectoryUnlocked(key.view()); +} + +gp::Expected MemoryMountBackend::createDirectoryTree(const gp::StringView relativePath) noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + if (key.isEmpty()) + { + return true; + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::StringView keyView = key.view(); + gp::USize scanPos = 0u; + while (scanPos < keyView.size()) + { + gp::USize nextSep = scanPos; + while (nextSep < keyView.size() && !gp::platform::Paths::isSeparator(keyView[nextSep])) + { + ++nextSep; + } + + const gp::StringView prefix = keyView.substr(0u, nextSep); + const gp::Expected res = createDirectoryUnlocked(prefix); + if (!res.hasValue()) + { + return res; + } + + scanPos = nextSep + 1u; + } + return true; +} + +gp::Expected MemoryMountBackend::removeFile(const gp::StringView relativePath) noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + if (key.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::USize idx = findNodeIndexUnlocked(key.view()); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (m_nodes[idx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + m_nodes[idx].relativePath.clear(); + m_nodes[idx].content.reset(); + m_nodes[idx].stats = {}; + m_nodes[idx].active = false; + return true; +} + +gp::Expected MemoryMountBackend::removeDirectory(const gp::StringView relativePath) noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + if (key.isEmpty()) + { + return gp::makeUnexpected(VfsError::AccessDenied); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::USize idx = findNodeIndexUnlocked(key.view()); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (!m_nodes[idx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (m_nodes[i].active && i != idx && + gp::platform::Paths::isUnderDirectory(m_nodes[i].relativePath.view(), key.view())) + { + return gp::makeUnexpected(VfsError::DirectoryNotEmpty); + } + } + + m_nodes[idx].relativePath.clear(); + m_nodes[idx].content.reset(); + m_nodes[idx].stats = {}; + m_nodes[idx].active = false; + return true; +} + +gp::Expected MemoryMountBackend::removeDirectoryTree(const gp::StringView relativePath) noexcept +{ + gp::PathBuffer key{}; + const VfsError normErr = normalizeRelativeKey(relativePath, key); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + if (key.isEmpty()) + { + return gp::makeUnexpected(VfsError::AccessDenied); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::USize idx = findNodeIndexUnlocked(key.view()); + if (idx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (!m_nodes[idx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (m_nodes[i].active && + (i == idx || gp::platform::Paths::isUnderDirectory(m_nodes[i].relativePath.view(), key.view()))) + { + m_nodes[i].relativePath.clear(); + m_nodes[i].content.reset(); + m_nodes[i].stats = {}; + m_nodes[i].active = false; + } + } + return true; +} + +gp::Expected MemoryMountBackend::move( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite +) noexcept +{ + gp::PathBuffer srcKey{}; + gp::PathBuffer dstKey{}; + const VfsError srcErr = normalizeRelativeKey(sourceRelativePath, srcKey); + const VfsError dstErr = normalizeRelativeKey(destinationRelativePath, dstKey); + if (srcErr != VfsError::None) + { + return gp::makeUnexpected(srcErr); + } + if (dstErr != VfsError::None) + { + return gp::makeUnexpected(dstErr); + } + if (srcKey.isEmpty() || dstKey.isEmpty()) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::USize srcIdx = findNodeIndexUnlocked(srcKey.view()); + if (srcIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (srcKey == dstKey) + { + return true; + } + + const gp::StringView dstParent = gp::platform::Paths::getPath(dstKey.view()); + const gp::USize dstParentIdx = findNodeIndexUnlocked(dstParent); + if (dstParentIdx >= kMaxMemoryMountNodes || !m_nodes[dstParentIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotFound); + } + + const gp::USize dstIdx = findNodeIndexUnlocked(dstKey.view()); + if (dstIdx < kMaxMemoryMountNodes) + { + if (!overwrite || m_nodes[dstIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::AlreadyExists); + } + m_nodes[dstIdx].relativePath.clear(); + m_nodes[dstIdx].content.reset(); + m_nodes[dstIdx].stats = {}; + m_nodes[dstIdx].active = false; + } + + const bool movingDirectory = m_nodes[srcIdx].stats.isDirectory(); + if (movingDirectory) + { + // Prevent moving a directory into its own descendant subtree + if (gp::platform::Paths::isUnderDirectory(dstKey.view(), srcKey.view())) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + // Reparent all active descendants under srcKey to the new dstKey prefix + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (!m_nodes[i].active || i == srcIdx) + { + continue; + } + const gp::StringView nodePath = m_nodes[i].relativePath.view(); + if (gp::platform::Paths::isUnderDirectory(nodePath, srcKey.view())) + { + const gp::StringView suffix = nodePath.substr(srcKey.size() + 1u); + const gp::PathBuffer reparented = gp::platform::Paths::combine(dstKey.view(), suffix); + m_nodes[i].relativePath = reparented; + } + } + } + + m_nodes[srcIdx].relativePath = dstKey; + return true; +} + +gp::Expected MemoryMountBackend::copyFile( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite +) noexcept +{ + gp::PathBuffer srcKey{}; + gp::PathBuffer dstKey{}; + const VfsError srcErr = normalizeRelativeKey(sourceRelativePath, srcKey); + const VfsError dstErr = normalizeRelativeKey(destinationRelativePath, dstKey); + if (srcErr != VfsError::None) + { + return gp::makeUnexpected(srcErr); + } + if (dstErr != VfsError::None) + { + return gp::makeUnexpected(dstErr); + } + if (srcKey.isEmpty() || dstKey.isEmpty()) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + if (srcKey == dstKey) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + const gp::thread::UniqueLock lock(m_mutex); + const gp::USize srcIdx = findNodeIndexUnlocked(srcKey.view()); + if (srcIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (m_nodes[srcIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::StringView dstParent = gp::platform::Paths::getPath(dstKey.view()); + const gp::USize dstParentIdx = findNodeIndexUnlocked(dstParent); + if (dstParentIdx >= kMaxMemoryMountNodes || !m_nodes[dstParentIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotFound); + } + + gp::USize dstIdx = findNodeIndexUnlocked(dstKey.view()); + if (dstIdx < kMaxMemoryMountNodes) + { + if (!overwrite || m_nodes[dstIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::AlreadyExists); + } + } + else + { + dstIdx = allocateNodeSlotUnlocked(); + if (dstIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::MountTableFull); + } + } + + const gp::time::Timestamp nowTs(gp::platform::Time::utcTimestampMicroseconds() * 1000ULL); + m_nodes[dstIdx].relativePath = dstKey; + m_nodes[dstIdx].content = m_nodes[srcIdx].content; + m_nodes[dstIdx].stats = m_nodes[srcIdx].stats; + m_nodes[dstIdx].stats.creationTime = nowTs; + m_nodes[dstIdx].stats.lastWriteTime = nowTs; + m_nodes[dstIdx].stats.lastAccessTime = nowTs; + m_nodes[dstIdx].active = true; + return true; +} + +gp::Expected MemoryMountBackend::iterateDirectory( + const gp::StringView relativeDirectoryPath, const gp::platform::DirectoryVisitorFn visitor, void* const userData +) const noexcept +{ + if (visitor == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + gp::PathBuffer dirKey{}; + const VfsError normErr = normalizeRelativeKey(relativeDirectoryPath, dirKey); + if (normErr != VfsError::None) + { + return gp::makeUnexpected(normErr); + } + + const gp::thread::SharedLock lock(m_mutex); + const gp::USize dirIdx = findNodeIndexUnlocked(dirKey.view()); + if (dirIdx >= kMaxMemoryMountNodes) + { + return gp::makeUnexpected(VfsError::NotFound); + } + if (!m_nodes[dirIdx].stats.isDirectory()) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + + for (gp::USize i = 0u; i < kMaxMemoryMountNodes; ++i) + { + if (!m_nodes[i].active || i == dirIdx || m_nodes[i].relativePath.isEmpty()) + { + continue; + } + + const gp::StringView nodeParent = gp::platform::Paths::getPath(m_nodes[i].relativePath.view()); + if (nodeParent != dirKey.view()) + { + continue; + } + + gp::platform::DirectoryEntry entry{}; + entry.path = m_nodes[i].relativePath.view(); + entry.name = gp::platform::Paths::getCleanFilename(entry.path); + entry.stats = m_nodes[i].stats; + entry.depth = 0u; + + const gp::platform::DirectoryVisitControl ctrl = visitor(entry, userData); + if (ctrl == gp::platform::DirectoryVisitControl::Stop) + { + break; + } + } + + return true; +} + +} // namespace gp::vfs diff --git a/source/runtime/core/private/vfs/PhysicalMountBackend.cpp b/source/runtime/core/private/vfs/PhysicalMountBackend.cpp new file mode 100644 index 00000000..de84551f --- /dev/null +++ b/source/runtime/core/private/vfs/PhysicalMountBackend.cpp @@ -0,0 +1,372 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "vfs/PhysicalMountBackend.hpp" +#include "platforms/base/system/FileSystem.hpp" +#include "platforms/base/system/Paths.hpp" + +namespace gp::vfs +{ + +PhysicalMountBackend::PhysicalMountBackend(const gp::StringView physicalRootDir) noexcept +{ + setRootPath(physicalRootDir); +} + +bool PhysicalMountBackend::setRootPath(const gp::StringView physicalRootDir) noexcept +{ + m_rootPath.clear(); + if (physicalRootDir.isEmpty() || physicalRootDir.size() > gp::platform::kMaxPathLength) + { + return false; + } + + m_rootPath.assign(physicalRootDir); + gp::platform::Paths::makeStandardFilename(m_rootPath); + gp::platform::Paths::ensureTrailingSeparator(m_rootPath); + return !m_rootPath.isEmpty(); +} + +gp::StringView PhysicalMountBackend::rootPath() const noexcept +{ + return m_rootPath.view(); +} + +bool PhysicalMountBackend::isPhysical() const noexcept +{ + return true; +} + +gp::Expected + PhysicalMountBackend::resolvePhysicalPath(const gp::StringView relativePath) const noexcept +{ + if (m_rootPath.isEmpty()) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + if (relativePath.isEmpty()) + { + gp::PathBuffer rootCopy(m_rootPath); + gp::platform::Paths::normalizeDirectoryName(rootCopy); + return rootCopy; + } + + gp::PathBuffer sanitizedRel(relativePath); + gp::platform::Paths::normalizeFilename(sanitizedRel); + if (!gp::platform::Paths::collapseRelativeDirectories(sanitizedRel)) + { + return gp::makeUnexpected(VfsError::SandboxEscapeViolation); + } + + const gp::StringView relView = sanitizedRel.view(); + if (relView == ".." || relView.startsWith("../") || !gp::platform::Paths::isRelative(relView)) + { + return gp::makeUnexpected(VfsError::SandboxEscapeViolation); + } + + if (relView.isEmpty() || relView == ".") + { + gp::PathBuffer rootCopy(m_rootPath); + gp::platform::Paths::normalizeDirectoryName(rootCopy); + return rootCopy; + } + + gp::PathBuffer combined = gp::platform::Paths::combine(m_rootPath.view(), relView); + gp::platform::Paths::normalizeDirectoryName(combined); + return combined; +} + +bool PhysicalMountBackend::exists(const gp::StringView relativePath) const noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return false; + } + return gp::platform::FileSystem::exists(phys.value().view()); +} + +gp::Expected + PhysicalMountBackend::getStats(const gp::StringView relativePath) const noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected stats = + gp::platform::FileSystem::getStats(phys.value().view()); + if (!stats.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(stats.error())); + } + return stats.value(); +} + +gp::Expected PhysicalMountBackend::openFileHandle( + const gp::StringView relativePath, + const gp::platform::FileAccessMode access, + const gp::platform::FileOpenMode openMode, + const gp::platform::FileShareMode shareMode +) noexcept +{ + if (relativePath.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + gp::Expected handleRes = + gp::platform::FileSystem::open(phys.value().view(), access, openMode, shareMode); + if (!handleRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(handleRes.error())); + } + return std::move(handleRes.value()); +} + +gp::Expected PhysicalMountBackend::readBytesAt( + const gp::StringView relativePath, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead +) const noexcept +{ + if (relativePath.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + gp::Expected openRes = + gp::platform::FileSystem::openRead(phys.value().view()); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(openRes.error())); + } + + const gp::Expected readRes = + openRes.value().readAt(offset, outBuffer, bytesToRead); + if (!readRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(readRes.error())); + } + return readRes.value(); +} + +gp::Expected PhysicalMountBackend::writeBytes( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes, const bool append +) noexcept +{ + if (relativePath.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected writeRes = + append ? gp::platform::FileSystem::appendAllBytes(phys.value().view(), data, sizeInBytes) + : gp::platform::FileSystem::writeAllBytes(phys.value().view(), data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(writeRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::writeAtomic( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes +) noexcept +{ + if (relativePath.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected writeRes = + gp::platform::FileSystem::writeAtomic(phys.value().view(), data, sizeInBytes); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(writeRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::createDirectory(const gp::StringView relativePath) noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected mkdirRes = + gp::platform::FileSystem::createDirectory(phys.value().view()); + if (!mkdirRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(mkdirRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::createDirectoryTree(const gp::StringView relativePath) noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected mkdirRes = + gp::platform::FileSystem::createDirectoryTree(phys.value().view()); + if (!mkdirRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(mkdirRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::removeFile(const gp::StringView relativePath) noexcept +{ + if (relativePath.isEmpty()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected rmRes = gp::platform::FileSystem::removeFile(phys.value().view()); + if (!rmRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(rmRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::removeDirectory(const gp::StringView relativePath) noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected rmRes = + gp::platform::FileSystem::removeDirectory(phys.value().view()); + if (!rmRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(rmRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::removeDirectoryTree(const gp::StringView relativePath) noexcept +{ + const gp::Expected phys = resolvePhysicalPath(relativePath); + if (!phys.hasValue()) + { + return gp::makeUnexpected(phys.error()); + } + + const gp::Expected rmRes = + gp::platform::FileSystem::removeDirectoryTree(phys.value().view()); + if (!rmRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(rmRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::move( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite +) noexcept +{ + const gp::Expected physSrc = resolvePhysicalPath(sourceRelativePath); + if (!physSrc.hasValue()) + { + return gp::makeUnexpected(physSrc.error()); + } + const gp::Expected physDst = resolvePhysicalPath(destinationRelativePath); + if (!physDst.hasValue()) + { + return gp::makeUnexpected(physDst.error()); + } + + const gp::Expected moveRes = + gp::platform::FileSystem::move(physSrc.value().view(), physDst.value().view(), overwrite); + if (!moveRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(moveRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::copyFile( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite +) noexcept +{ + const gp::Expected physSrc = resolvePhysicalPath(sourceRelativePath); + if (!physSrc.hasValue()) + { + return gp::makeUnexpected(physSrc.error()); + } + const gp::Expected physDst = resolvePhysicalPath(destinationRelativePath); + if (!physDst.hasValue()) + { + return gp::makeUnexpected(physDst.error()); + } + + const gp::Expected copyRes = + gp::platform::FileSystem::copyFile(physSrc.value().view(), physDst.value().view(), overwrite); + if (!copyRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(copyRes.error())); + } + return true; +} + +gp::Expected PhysicalMountBackend::iterateDirectory( + const gp::StringView relativeDirectoryPath, const gp::platform::DirectoryVisitorFn visitor, void* const userData +) const noexcept +{ + const gp::Expected physDir = resolvePhysicalPath(relativeDirectoryPath); + if (!physDir.hasValue()) + { + return gp::makeUnexpected(physDir.error()); + } + + const gp::Expected iterRes = + gp::platform::FileSystem::iterateDirectory(physDir.value().view(), visitor, userData); + if (!iterRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(iterRes.error())); + } + return true; +} + +} // namespace gp::vfs diff --git a/source/runtime/core/private/vfs/VirtualFileSystem.cpp b/source/runtime/core/private/vfs/VirtualFileSystem.cpp new file mode 100644 index 00000000..423daf21 --- /dev/null +++ b/source/runtime/core/private/vfs/VirtualFileSystem.cpp @@ -0,0 +1,1994 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "vfs/VirtualFileSystem.hpp" +#include "console/AutoConsoleVariable.hpp" +#include "console/ConsoleEnums.hpp" +#include "console/ConsoleTypes.hpp" +#include "containers/strings/FixedString.hpp" +#include "hashing/Fnv1a.hpp" +#include "logging/LogFormatter.hpp" +#include "platforms/base/system/Paths.hpp" +#include "threading/sync/SharedLock.hpp" +#include "threading/sync/SharedMutex.hpp" +#include "threading/sync/UniqueLock.hpp" +#include "vfs/PhysicalMountBackend.hpp" + +namespace gp::vfs +{ + +namespace detail +{ + +/// @brief Internal slot inside the zero-allocation `.bss` VFS mount table. +struct MountTableSlot +{ + SchemeBuffer scheme{}; + IMountBackend* backend{ nullptr }; + MountPriority priority{ MountPriority::Base }; + MountAccess access{ MountAccess::ReadOnly }; + gp::UInt32 registrationOrder{ 0u }; + bool ownsPhysicalSlot{ false }; + gp::USize physicalSlotIndex{ 0u }; + bool active{ false }; +}; + +/// @brief Zero-allocation `.bss` state for `gp::vfs::VirtualFileSystem`. +struct VfsGlobalState +{ + gp::thread::SharedMutex mutex{}; + MountTableSlot mounts[kMaxMountPoints]{}; + PhysicalMountBackend physicalBackends[kMaxMountPoints]{}; + bool physicalSlotUsed[kMaxMountPoints]{}; + gp::UInt32 nextRegistrationOrder{ 1u }; +}; + +/// @brief Returns the function-local static `.bss` VFS state instance. +/// @return Reference to `VfsGlobalState`. +[[nodiscard]] static VfsGlobalState& getState() noexcept +{ + static VfsGlobalState s_state{}; + return s_state; +} + +/// @brief Gathers active mount slots matching `normalizedScheme` sorted in descending priority order (and descending +/// registration order as a tie-breaker so later mounts at the same priority win). +/// @param[in] state Reference to `VfsGlobalState` (caller must hold shared or exclusive `state.mutex`). +/// @param[in] normalizedScheme Canonical lowercase scheme (e.g., `"game://"`). +/// @param[out] outIndices Receives sorted slot indices into `state.mounts`. +/// @return Number of matching mounts written to `outIndices`. +[[nodiscard]] static gp::USize collectSortedMountsForSchemeUnlocked( + const VfsGlobalState& state, const gp::StringView normalizedScheme, gp::USize (&outIndices)[kMaxMountPoints] +) noexcept +{ + gp::USize count = 0u; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].backend != nullptr && + state.mounts[i].scheme.view() == normalizedScheme) + { + outIndices[count] = i; + ++count; + } + } + + // Insertion sort by descending priority, then descending registrationOrder (most recent mount wins ties). + for (gp::USize i = 1u; i < count; ++i) + { + const gp::USize keyIdx = outIndices[i]; + const gp::UInt16 keyPrio = static_cast(state.mounts[keyIdx].priority); + const gp::UInt32 keyOrder = state.mounts[keyIdx].registrationOrder; + + gp::USize j = i; + while (j > 0u) + { + const gp::USize prevIdx = outIndices[j - 1u]; + const gp::UInt16 prevPrio = static_cast(state.mounts[prevIdx].priority); + const gp::UInt32 prevOrder = state.mounts[prevIdx].registrationOrder; + + if (keyPrio > prevPrio || (keyPrio == prevPrio && keyOrder > prevOrder)) + { + outIndices[j] = prevIdx; + --j; + } + else + { + break; + } + } + outIndices[j] = keyIdx; + } + + return count; +} + +/// @brief Finds the highest-priority `MountAccess::ReadWrite` backend for `normalizedScheme` (caller holds lock). +/// @param[in] state Reference to `VfsGlobalState`. +/// @param[in] normalizedScheme Canonical lowercase scheme. +/// @param[out] outError Receives `SchemeNotMounted` if no mounts exist for the scheme, or `ReadOnlyMount` if all +/// mounts for the scheme are `ReadOnly`. +/// @return Pointer to the winning writable `IMountBackend`, or `nullptr` on error. +[[nodiscard]] static IMountBackend* findWritableBackendUnlocked( + const VfsGlobalState& state, const gp::StringView normalizedScheme, VfsError& outError +) noexcept +{ + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = collectSortedMountsForSchemeUnlocked(state, normalizedScheme, sorted); + if (count == 0u) + { + outError = VfsError::SchemeNotMounted; + return nullptr; + } + + for (gp::USize i = 0u; i < count; ++i) + { + const MountTableSlot& slot = state.mounts[sorted[i]]; + if (slot.access == MountAccess::ReadWrite) + { + outError = VfsError::None; + return slot.backend; + } + } + + outError = VfsError::ReadOnlyMount; + return nullptr; +} + +/// @brief Releases a mount slot and its owned `PhysicalMountBackend` slot if applicable (caller holds exclusive lock). +/// @param[in,out] state Reference to `VfsGlobalState`. +/// @param[in] slotIndex Index in `state.mounts` to clear. +static void releaseMountSlotUnlocked(VfsGlobalState& state, const gp::USize slotIndex) noexcept +{ + MountTableSlot& slot = state.mounts[slotIndex]; + if (slot.ownsPhysicalSlot && slot.physicalSlotIndex < kMaxMountPoints) + { + state.physicalBackends[slot.physicalSlotIndex].setRootPath(""); + state.physicalSlotUsed[slot.physicalSlotIndex] = false; + } + + slot.scheme.clear(); + slot.backend = nullptr; + slot.priority = MountPriority::Base; + slot.access = MountAccess::ReadOnly; + slot.registrationOrder = 0u; + slot.ownsPhysicalSlot = false; + slot.physicalSlotIndex = 0u; + slot.active = false; +} + +/// @brief Formats a canonical VFS URI from a scheme (`"game://"`) and relative path (`"textures/hero.ktx2"`). +/// @param[in] scheme Canonical scheme including `"://"`. +/// @param[in] relativePath Normalized relative path without leading slash. +/// @return Combined `PathBuffer` holding `"scheme://relativePath"`. +[[nodiscard]] static gp::PathBuffer + buildCanonicalUri(const gp::StringView scheme, const gp::StringView relativePath) noexcept +{ + gp::PathBuffer uri(scheme); + gp::StringView rel = relativePath; + while (!rel.isEmpty() && gp::platform::Paths::isSeparator(rel.front())) + { + rel = rel.substr(1u); + } + uri.append(rel); + return uri; +} + +/// @brief Recursive implementation for `VirtualFileSystem::iterateDirectoryRecursive`. +/// @param[in] directoryUri Current VFS directory URI. +/// @param[in] visitor User callback. +/// @param[in] userData User context pointer. +/// @param[in] depth Current recursion depth (`0` at root). +/// @param[out] outStopped Set to true if `visitor` returned `DirectoryVisitControl::Stop`. +/// @return `Expected`. +[[nodiscard]] static gp::Expected iterateDirectoryRecursiveInternal( + const gp::StringView directoryUri, + const VfsDirectoryVisitorFn visitor, + void* const userData, + const gp::UInt32 depth, + bool& outStopped +) noexcept +{ + if (visitor == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + if (depth > gp::platform::kMaxDirectoryRecursionDepth) + { + return gp::makeUnexpected(VfsError::MaxRecursionDepthExceeded); + } + + struct VfsRecursiveState + { + VfsDirectoryVisitorFn userVisitor{ nullptr }; + void* userContext{ nullptr }; + gp::UInt32 currentDepth{ 0u }; + VfsError childError{ VfsError::None }; + bool stopped{ false }; + }; + + VfsRecursiveState state{}; + state.userVisitor = visitor; + state.userContext = userData; + state.currentDepth = depth; + + const VfsDirectoryVisitorFn stepVisitor = [](const VfsDirectoryEntry& rawEntry, + void* const rawState) -> gp::platform::DirectoryVisitControl + { + VfsRecursiveState* const walk = static_cast(rawState); + VfsDirectoryEntry entryWithDepth = rawEntry; + entryWithDepth.depth = walk->currentDepth; + + const gp::platform::DirectoryVisitControl ctrl = walk->userVisitor(entryWithDepth, walk->userContext); + if (ctrl == gp::platform::DirectoryVisitControl::Stop) + { + walk->stopped = true; + return gp::platform::DirectoryVisitControl::Stop; + } + + if (entryWithDepth.isDirectory() && !entryWithDepth.stats.isSymbolicLink() && + ctrl != gp::platform::DirectoryVisitControl::SkipSubdirectory) + { + const gp::Expected childRes = iterateDirectoryRecursiveInternal( + entryWithDepth.uri, walk->userVisitor, walk->userContext, walk->currentDepth + 1u, walk->stopped + ); + if (!childRes.hasValue()) + { + walk->childError = childRes.error(); + return gp::platform::DirectoryVisitControl::Stop; + } + if (walk->stopped) + { + return gp::platform::DirectoryVisitControl::Stop; + } + } + + return gp::platform::DirectoryVisitControl::Continue; + }; + + const gp::Expected iterRes = VirtualFileSystem::iterateDirectory(directoryUri, stepVisitor, &state); + if (!iterRes.hasValue()) + { + return iterRes; + } + if (state.childError != VfsError::None) + { + return gp::makeUnexpected(state.childError); + } + + outStopped = state.stopped; + return true; +} + +} // namespace detail + +gp::Expected VirtualFileSystem::initializeDefaultMounts(const gp::StringView appName) noexcept +{ + const gp::StringView effectiveApp = !appName.isEmpty() ? appName + : (!gp::platform::Paths::executableName(true).isEmpty() + ? gp::platform::Paths::executableName(true) + : gp::StringView("gp-engine")); + + const gp::PathBuffer engineRoot = gp::platform::Paths::combine(gp::platform::Paths::baseDir(), "engine"); + const gp::PathBuffer gameRoot = gp::platform::Paths::combine(gp::platform::Paths::baseDir(), "content"); + const gp::PathBuffer userRoot = gp::platform::Paths::combine(gp::platform::Paths::documentsDir(), effectiveApp); + const gp::PathBuffer appDataRoot = gp::platform::Paths::combine(gp::platform::Paths::appDataDir(), effectiveApp); + const gp::PathBuffer cacheRoot = + gp::platform::Paths::combine(gp::platform::Paths::localAppDataDir(), effectiveApp, "cache"); + const gp::PathBuffer tempRoot = gp::platform::Paths::combine(gp::platform::Paths::tempDir(), effectiveApp); + + const gp::Expected r1 = + mount(kEngineScheme, engineRoot.view(), MountPriority::Base, MountAccess::ReadOnly); + if (!r1.hasValue()) + { + return r1; + } + + const gp::Expected r2 = + mount(kGameScheme, gameRoot.view(), MountPriority::Base, MountAccess::ReadOnly); + if (!r2.hasValue()) + { + return r2; + } + + const gp::Expected r3 = + mount(kUserScheme, userRoot.view(), MountPriority::Base, MountAccess::ReadWrite); + if (!r3.hasValue()) + { + return r3; + } + + const gp::Expected r4 = + mount(kAppDataScheme, appDataRoot.view(), MountPriority::Base, MountAccess::ReadWrite); + if (!r4.hasValue()) + { + return r4; + } + + const gp::Expected r5 = + mount(kCacheScheme, cacheRoot.view(), MountPriority::Base, MountAccess::ReadWrite); + if (!r5.hasValue()) + { + return r5; + } + + const gp::Expected r6 = + mount(kTempScheme, tempRoot.view(), MountPriority::Base, MountAccess::ReadWrite); + if (!r6.hasValue()) + { + return r6; + } + + return true; +} + +void VirtualFileSystem::shutdown() noexcept +{ + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active) + { + detail::releaseMountSlotUnlocked(state, i); + } + } + state.nextRegistrationOrder = 1u; +} + +bool VirtualFileSystem::normalizeScheme(const gp::StringView rawScheme, SchemeBuffer& outScheme) noexcept +{ + outScheme.clear(); + if (rawScheme.isEmpty()) + { + return false; + } + + gp::StringView trimmed = rawScheme; + if (trimmed.endsWith("://")) + { + trimmed = trimmed.substr(0u, trimmed.size() - 3u); + } + else if (trimmed.endsWith(":")) + { + trimmed = trimmed.substr(0u, trimmed.size() - 1u); + } + + // Reject single-character schemes (e.g., Windows drive letters "C:") or schemes exceeding buffer limits + if (trimmed.size() < 2u || (trimmed.size() + 3u) > kMaxSchemeLength) + { + return false; + } + if (!gp::platform::Paths::isAsciiAlpha(trimmed[0])) + { + return false; + } + + for (gp::USize i = 0u; i < trimmed.size(); ++i) + { + const char ch = trimmed[i]; + if (!gp::platform::Paths::isAsciiAlphaNumeric(ch) && ch != '+' && ch != '-' && ch != '.') + { + return false; + } + outScheme.pushBack(gp::platform::Paths::toLowerAscii(ch)); + } + + outScheme.append("://"); + return true; +} + +gp::Expected VirtualFileSystem::parseUri(const gp::StringView uri) noexcept +{ + if (uri.isEmpty() || uri.size() > gp::platform::kMaxPathLength) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + const gp::USize schemeDelimPos = uri.find("://"); + if (schemeDelimPos == gp::StringView::npos || schemeDelimPos < 2u) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + ParsedUri parsed{}; + if (!normalizeScheme(uri.substr(0u, schemeDelimPos + 3u), parsed.scheme)) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + gp::StringView rawSubPath = uri.substr(schemeDelimPos + 3u); + while (!rawSubPath.isEmpty() && gp::platform::Paths::isSeparator(rawSubPath.front())) + { + rawSubPath = rawSubPath.substr(1u); + } + + if (rawSubPath.isEmpty()) + { + return parsed; + } + + // Reject drive specifiers or embedded colons inside the relative sub-path (e.g. "game://C:/Windows") + for (gp::USize i = 0u; i < rawSubPath.size(); ++i) + { + if (rawSubPath[i] == ':') + { + return gp::makeUnexpected(VfsError::SandboxEscapeViolation); + } + } + + gp::PathBuffer collapsed(rawSubPath); + gp::platform::Paths::normalizeDirectoryName(collapsed); + if (!gp::platform::Paths::collapseRelativeDirectories(collapsed)) + { + return gp::makeUnexpected(VfsError::SandboxEscapeViolation); + } + + gp::StringView cleanView = collapsed.view(); + while (!cleanView.isEmpty() && gp::platform::Paths::isSeparator(cleanView.front())) + { + cleanView = cleanView.substr(1u); + } + while (!cleanView.isEmpty() && gp::platform::Paths::isSeparator(cleanView.back())) + { + cleanView = cleanView.substr(0u, cleanView.size() - 1u); + } + + if (cleanView == ".." || cleanView.startsWith("../")) + { + return gp::makeUnexpected(VfsError::SandboxEscapeViolation); + } + if (cleanView == ".") + { + cleanView = {}; + } + + parsed.relativePath.assign(cleanView); + return parsed; +} + +gp::Expected VirtualFileSystem::mount( + const gp::StringView scheme, + const gp::StringView physicalRootDir, + const MountPriority priority, + const MountAccess access +) noexcept +{ + SchemeBuffer normScheme{}; + if (!normalizeScheme(scheme, normScheme) || physicalRootDir.isEmpty()) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + gp::PathBuffer normalizedRoot(physicalRootDir); + gp::platform::Paths::makeStandardFilename(normalizedRoot); + gp::platform::Paths::ensureTrailingSeparator(normalizedRoot); + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + // If an identical scheme + physical root mount already exists, update its priority and access in place. + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].scheme.view() == normScheme.view() && + state.mounts[i].backend != nullptr && + gp::platform::Paths::equals(state.mounts[i].backend->rootPath(), normalizedRoot.view())) + { + state.mounts[i].priority = priority; + state.mounts[i].access = access; + state.mounts[i].registrationOrder = state.nextRegistrationOrder++; + return true; + } + } + + gp::USize mountSlot = kMaxMountPoints; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (!state.mounts[i].active) + { + mountSlot = i; + break; + } + } + + gp::USize physSlot = kMaxMountPoints; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (!state.physicalSlotUsed[i]) + { + physSlot = i; + break; + } + } + + if (mountSlot >= kMaxMountPoints || physSlot >= kMaxMountPoints) + { + return gp::makeUnexpected(VfsError::MountTableFull); + } + + if (!state.physicalBackends[physSlot].setRootPath(normalizedRoot.view())) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + state.physicalSlotUsed[physSlot] = true; + + detail::MountTableSlot& slot = state.mounts[mountSlot]; + slot.scheme = normScheme; + slot.backend = &state.physicalBackends[physSlot]; + slot.priority = priority; + slot.access = access; + slot.registrationOrder = state.nextRegistrationOrder++; + slot.ownsPhysicalSlot = true; + slot.physicalSlotIndex = physSlot; + slot.active = true; + + return true; +} + +gp::Expected VirtualFileSystem::mountBackend( + const gp::StringView scheme, IMountBackend* const backend, const MountPriority priority, const MountAccess access +) noexcept +{ + if (backend == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + SchemeBuffer normScheme{}; + if (!normalizeScheme(scheme, normScheme)) + { + return gp::makeUnexpected(VfsError::InvalidUri); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].scheme.view() == normScheme.view() && + state.mounts[i].backend == backend) + { + state.mounts[i].priority = priority; + state.mounts[i].access = access; + state.mounts[i].registrationOrder = state.nextRegistrationOrder++; + return true; + } + } + + gp::USize mountSlot = kMaxMountPoints; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (!state.mounts[i].active) + { + mountSlot = i; + break; + } + } + + if (mountSlot >= kMaxMountPoints) + { + return gp::makeUnexpected(VfsError::MountTableFull); + } + + detail::MountTableSlot& slot = state.mounts[mountSlot]; + slot.scheme = normScheme; + slot.backend = backend; + slot.priority = priority; + slot.access = access; + slot.registrationOrder = state.nextRegistrationOrder++; + slot.ownsPhysicalSlot = false; + slot.physicalSlotIndex = 0u; + slot.active = true; + + return true; +} + +bool VirtualFileSystem::unmount(const gp::StringView scheme, const gp::StringView rootPath) noexcept +{ + SchemeBuffer normScheme{}; + if (!normalizeScheme(scheme, normScheme) || rootPath.isEmpty()) + { + return false; + } + + gp::PathBuffer normalizedTarget(rootPath); + gp::platform::Paths::makeStandardFilename(normalizedTarget); + gp::platform::Paths::ensureTrailingSeparator(normalizedTarget); + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].scheme.view() == normScheme.view() && + state.mounts[i].backend != nullptr) + { + const gp::StringView backendRoot = state.mounts[i].backend->rootPath(); + if (backendRoot == rootPath || gp::platform::Paths::equals(backendRoot, normalizedTarget.view())) + { + detail::releaseMountSlotUnlocked(state, i); + return true; + } + } + } + + return false; +} + +bool VirtualFileSystem::unmountBackend(const gp::StringView scheme, const IMountBackend* const backend) noexcept +{ + SchemeBuffer normScheme{}; + if (backend == nullptr || !normalizeScheme(scheme, normScheme)) + { + return false; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].scheme.view() == normScheme.view() && + state.mounts[i].backend == backend) + { + detail::releaseMountSlotUnlocked(state, i); + return true; + } + } + + return false; +} + +gp::USize VirtualFileSystem::unmountScheme(const gp::StringView scheme) noexcept +{ + SchemeBuffer normScheme{}; + if (!normalizeScheme(scheme, normScheme)) + { + return 0u; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::UniqueLock lock(state.mutex); + + gp::USize removedCount = 0u; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].scheme.view() == normScheme.view()) + { + detail::releaseMountSlotUnlocked(state, i); + ++removedCount; + } + } + return removedCount; +} + +bool VirtualFileSystem::isSchemeMounted(const gp::StringView scheme) noexcept +{ + return getMountCount(scheme) > 0u; +} + +gp::USize VirtualFileSystem::getMountCount(const gp::StringView scheme) noexcept +{ + SchemeBuffer normScheme{}; + if (!scheme.isEmpty() && !normalizeScheme(scheme, normScheme)) + { + return 0u; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize count = 0u; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active) + { + if (normScheme.isEmpty() || state.mounts[i].scheme.view() == normScheme.view()) + { + ++count; + } + } + } + return count; +} + +gp::USize VirtualFileSystem::enumerateMounts( + const gp::StringView scheme, const MountPointVisitorFn visitor, void* const userData +) noexcept +{ + if (visitor == nullptr) + { + return 0u; + } + + SchemeBuffer normScheme{}; + if (!scheme.isEmpty() && !normalizeScheme(scheme, normScheme)) + { + return 0u; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize matchingIndices[kMaxMountPoints]{}; + gp::USize count = 0u; + for (gp::USize i = 0u; i < kMaxMountPoints; ++i) + { + if (state.mounts[i].active && state.mounts[i].backend != nullptr) + { + if (normScheme.isEmpty() || state.mounts[i].scheme.view() == normScheme.view()) + { + matchingIndices[count] = i; + ++count; + } + } + } + + // Sort deterministically by ascending scheme name, then descending priority, then descending registration order. + for (gp::USize i = 1u; i < count; ++i) + { + const gp::USize keyIdx = matchingIndices[i]; + const detail::MountTableSlot& keySlot = state.mounts[keyIdx]; + const gp::UInt16 keyPrio = static_cast(keySlot.priority); + + gp::USize j = i; + while (j > 0u) + { + const gp::USize prevIdx = matchingIndices[j - 1u]; + const detail::MountTableSlot& prevSlot = state.mounts[prevIdx]; + const gp::Int32 schemeCmp = keySlot.scheme.view().compare(prevSlot.scheme.view()); + const gp::UInt16 prevPrio = static_cast(prevSlot.priority); + + const bool shouldComeBefore = + (schemeCmp < 0) || + (schemeCmp == 0 && (keyPrio > prevPrio || + (keyPrio == prevPrio && keySlot.registrationOrder > prevSlot.registrationOrder))); + if (shouldComeBefore) + { + matchingIndices[j] = prevIdx; + --j; + } + else + { + break; + } + } + matchingIndices[j] = keyIdx; + } + + gp::USize visited = 0u; + MountPointDesc desc{}; + for (gp::USize i = 0u; i < count; ++i) + { + const detail::MountTableSlot& slot = state.mounts[matchingIndices[i]]; + desc.scheme.assign(slot.scheme.view()); + desc.rootPath.assign(slot.backend->rootPath()); + desc.priority = slot.priority; + desc.access = slot.access; + + ++visited; + if (!visitor(desc, userData)) + { + break; + } + } + + return visited; +} + +gp::Expected VirtualFileSystem::resolvePhysicalPath(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + if (count == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + IMountBackend* highestPhysical = nullptr; + for (gp::USize i = 0u; i < count; ++i) + { + IMountBackend* const backend = state.mounts[sorted[i]].backend; + if (backend->isPhysical()) + { + if (highestPhysical == nullptr) + { + highestPhysical = backend; + } + if (backend->exists(parsed.value().relativePath.view())) + { + return backend->resolvePhysicalPath(parsed.value().relativePath.view()); + } + } + } + + if (highestPhysical != nullptr) + { + return highestPhysical->resolvePhysicalPath(parsed.value().relativePath.view()); + } + + return gp::makeUnexpected(VfsError::NotSupported); +} + +gp::Expected VirtualFileSystem::resolveWritablePhysicalPath(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->resolvePhysicalPath(parsed.value().relativePath.view()); +} + +bool VirtualFileSystem::exists(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return false; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + for (gp::USize i = 0u; i < count; ++i) + { + if (state.mounts[sorted[i]].backend->exists(parsed.value().relativePath.view())) + { + return true; + } + } + return false; +} + +bool VirtualFileSystem::isFile(const gp::StringView uri) noexcept +{ + const gp::Expected stats = getStats(uri); + return stats.hasValue() && stats.value().isFile(); +} + +bool VirtualFileSystem::isDirectory(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return false; + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + for (gp::USize i = 0u; i < count; ++i) + { + const gp::Expected stats = + state.mounts[sorted[i]].backend->getStats(parsed.value().relativePath.view()); + if (stats.hasValue()) + { + return stats.value().isDirectory(); + } + } + return false; +} + +gp::Expected VirtualFileSystem::getStats(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + if (count == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + for (gp::USize i = 0u; i < count; ++i) + { + const gp::Expected stats = + state.mounts[sorted[i]].backend->getStats(parsed.value().relativePath.view()); + if (stats.hasValue()) + { + return stats.value(); + } + } + + return gp::makeUnexpected(VfsError::NotFound); +} + +gp::Expected VirtualFileSystem::fileSize(const gp::StringView uri) noexcept +{ + const gp::Expected stats = getStats(uri); + if (!stats.hasValue()) + { + return gp::makeUnexpected(stats.error()); + } + if (stats.value().isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + return stats.value().size; +} + +gp::Expected + VirtualFileSystem::openRead(const gp::StringView uri, const gp::platform::FileShareMode shareMode) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + if (count == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + VfsError lastErr = VfsError::NotFound; + for (gp::USize i = 0u; i < count; ++i) + { + IMountBackend* const backend = state.mounts[sorted[i]].backend; + if (!backend->exists(parsed.value().relativePath.view())) + { + continue; + } + + gp::Expected openRes = backend->openFileHandle( + parsed.value().relativePath.view(), + gp::platform::FileAccessMode::Read, + gp::platform::FileOpenMode::OpenExisting, + shareMode + ); + if (openRes.hasValue()) + { + return std::move(openRes.value()); + } + lastErr = openRes.error(); + if (lastErr != VfsError::NotFound) + { + break; + } + } + + return gp::makeUnexpected(lastErr); +} + +gp::Expected VirtualFileSystem::openWrite( + const gp::StringView uri, const bool append, const bool allowRead, const gp::platform::FileShareMode shareMode +) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + const gp::platform::FileAccessMode access = + allowRead ? gp::platform::FileAccessMode::ReadWrite : gp::platform::FileAccessMode::Write; + const gp::platform::FileOpenMode mode = + append ? gp::platform::FileOpenMode::Append : gp::platform::FileOpenMode::CreateAlways; + + return writable->openFileHandle(parsed.value().relativePath.view(), access, mode, shareMode); +} + +gp::Expected VirtualFileSystem::createDirectory(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->createDirectory(parsed.value().relativePath.view()); +} + +gp::Expected VirtualFileSystem::createDirectoryTree(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->createDirectoryTree(parsed.value().relativePath.view()); +} + +gp::Expected VirtualFileSystem::removeFile(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->removeFile(parsed.value().relativePath.view()); +} + +gp::Expected VirtualFileSystem::removeDirectory(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->removeDirectory(parsed.value().relativePath.view()); +} + +gp::Expected VirtualFileSystem::removeDirectoryTree(const gp::StringView uri) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->removeDirectoryTree(parsed.value().relativePath.view()); +} + +gp::Expected VirtualFileSystem::move( + const gp::StringView sourceUri, const gp::StringView destinationUri, const bool overwrite +) noexcept +{ + const gp::Expected parsedSrc = parseUri(sourceUri); + if (!parsedSrc.hasValue()) + { + return gp::makeUnexpected(parsedSrc.error()); + } + const gp::Expected parsedDst = parseUri(destinationUri); + if (!parsedDst.hasValue()) + { + return gp::makeUnexpected(parsedDst.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError srcErr = VfsError::None; + IMountBackend* const srcWritable = + detail::findWritableBackendUnlocked(state, parsedSrc.value().scheme.view(), srcErr); + if (srcWritable == nullptr) + { + return gp::makeUnexpected(srcErr); + } + + VfsError dstErr = VfsError::None; + IMountBackend* const dstWritable = + detail::findWritableBackendUnlocked(state, parsedDst.value().scheme.view(), dstErr); + if (dstWritable == nullptr) + { + return gp::makeUnexpected(dstErr); + } + + if (srcWritable != dstWritable) + { + return gp::makeUnexpected(VfsError::CrossMountOperation); + } + + return srcWritable->move(parsedSrc.value().relativePath.view(), parsedDst.value().relativePath.view(), overwrite); +} + +gp::Expected VirtualFileSystem::copyFile( + const gp::StringView sourceUri, const gp::StringView destinationUri, const bool overwrite +) noexcept +{ + const gp::Expected parsedSrc = parseUri(sourceUri); + if (!parsedSrc.hasValue()) + { + return gp::makeUnexpected(parsedSrc.error()); + } + const gp::Expected parsedDst = parseUri(destinationUri); + if (!parsedDst.hasValue()) + { + return gp::makeUnexpected(parsedDst.error()); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sortedSrc[kMaxMountPoints]{}; + const gp::USize srcCount = + detail::collectSortedMountsForSchemeUnlocked(state, parsedSrc.value().scheme.view(), sortedSrc); + if (srcCount == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + IMountBackend* srcBackend = nullptr; + for (gp::USize i = 0u; i < srcCount; ++i) + { + if (state.mounts[sortedSrc[i]].backend->exists(parsedSrc.value().relativePath.view())) + { + srcBackend = state.mounts[sortedSrc[i]].backend; + break; + } + } + if (srcBackend == nullptr) + { + return gp::makeUnexpected(VfsError::NotFound); + } + + VfsError dstErr = VfsError::None; + IMountBackend* const dstWritable = + detail::findWritableBackendUnlocked(state, parsedDst.value().scheme.view(), dstErr); + if (dstWritable == nullptr) + { + return gp::makeUnexpected(dstErr); + } + + if (srcBackend == dstWritable) + { + return dstWritable->copyFile( + parsedSrc.value().relativePath.view(), parsedDst.value().relativePath.view(), overwrite + ); + } + + if (!overwrite && dstWritable->exists(parsedDst.value().relativePath.view())) + { + return gp::makeUnexpected(VfsError::AlreadyExists); + } + + const gp::Expected srcStats = + srcBackend->getStats(parsedSrc.value().relativePath.view()); + if (!srcStats.hasValue()) + { + return gp::makeUnexpected(srcStats.error()); + } + if (srcStats.value().isDirectory()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + const gp::UInt64 totalBytes = srcStats.value().size; + if (totalBytes == 0ULL) + { + return dstWritable->writeBytes(parsedDst.value().relativePath.view(), nullptr, 0u, false); + } + + // Cross-mount copy: if both source and destination are physical mounts, keep both handles open across all chunks + // (or open a single destination handle when copying from a non-physical backend) instead of reopening per 16 KiB. + if (dstWritable->isPhysical()) + { + gp::Expected dstHandleRes = dstWritable->openFileHandle( + parsedDst.value().relativePath.view(), + gp::platform::FileAccessMode::Write, + overwrite ? gp::platform::FileOpenMode::CreateAlways : gp::platform::FileOpenMode::CreateNew, + gp::platform::FileShareMode::None + ); + if (!dstHandleRes.hasValue()) + { + return gp::makeUnexpected(dstHandleRes.error()); + } + + gp::platform::FileHandle& dstHandle = dstHandleRes.value(); + gp::Expected srcHandleRes = gp::makeUnexpected(VfsError::NotSupported); + if (srcBackend->isPhysical()) + { + srcHandleRes = srcBackend->openFileHandle( + parsedSrc.value().relativePath.view(), + gp::platform::FileAccessMode::Read, + gp::platform::FileOpenMode::OpenExisting, + gp::platform::FileShareMode::ReadWrite + ); + if (!srcHandleRes.hasValue()) + { + return gp::makeUnexpected(srcHandleRes.error()); + } + } + + gp::Byte chunkBuf[gp::platform::kFileCopyChunkSize]{}; + gp::UInt64 offset = 0ULL; + + while (offset < totalBytes) + { + const gp::UInt64 remaining = totalBytes - offset; + const gp::USize toRead = (remaining > static_cast(gp::platform::kFileCopyChunkSize)) + ? gp::platform::kFileCopyChunkSize + : static_cast(remaining); + + gp::USize bytesRead = 0u; + if (srcHandleRes.hasValue()) + { + const gp::Expected readRes = + srcHandleRes.value().read(chunkBuf, toRead); + if (!readRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(readRes.error())); + } + bytesRead = readRes.value(); + } + else + { + const gp::Expected readRes = + srcBackend->readBytesAt(parsedSrc.value().relativePath.view(), offset, chunkBuf, toRead); + if (!readRes.hasValue()) + { + return gp::makeUnexpected(readRes.error()); + } + bytesRead = readRes.value(); + } + + if (bytesRead == 0u) + { + break; + } + + const gp::Expected writeRes = dstHandle.write(chunkBuf, bytesRead); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(mapFileErrorToVfsError(writeRes.error())); + } + if (writeRes.value() != bytesRead) + { + return gp::makeUnexpected(VfsError::DiskFull); + } + + offset += static_cast(bytesRead); + } + return true; + } + + gp::Byte chunkBuf[gp::platform::kFileCopyChunkSize]{}; + gp::UInt64 offset = 0ULL; + bool firstChunk = true; + + while (offset < totalBytes) + { + const gp::UInt64 remaining = totalBytes - offset; + const gp::USize toRead = (remaining > static_cast(gp::platform::kFileCopyChunkSize)) + ? gp::platform::kFileCopyChunkSize + : static_cast(remaining); + + const gp::Expected readRes = + srcBackend->readBytesAt(parsedSrc.value().relativePath.view(), offset, chunkBuf, toRead); + if (!readRes.hasValue()) + { + return gp::makeUnexpected(readRes.error()); + } + if (readRes.value() == 0u) + { + break; + } + + const gp::Expected writeRes = + dstWritable->writeBytes(parsedDst.value().relativePath.view(), chunkBuf, readRes.value(), !firstChunk); + if (!writeRes.hasValue()) + { + return gp::makeUnexpected(writeRes.error()); + } + + offset += static_cast(readRes.value()); + firstChunk = false; + } + + return true; +} + +gp::Expected VirtualFileSystem::iterateDirectory( + const gp::StringView directoryUri, const VfsDirectoryVisitorFn visitor, void* const userData +) noexcept +{ + if (visitor == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + const gp::Expected parsed = parseUri(directoryUri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + + IMountBackend* activeBackends[kMaxMountPoints]{}; + MountPriority activePriorities[kMaxMountPoints]{}; + gp::USize mountCount = 0u; + + { + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + mountCount = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + if (mountCount == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + for (gp::USize i = 0u; i < mountCount; ++i) + { + activeBackends[i] = state.mounts[sorted[i]].backend; + activePriorities[i] = state.mounts[sorted[i]].priority; + } + } + + constexpr gp::USize kSeenTableCapacity = kVfsMergedDirectoryHashSlots; + constexpr gp::USize kSeenTableMask = kSeenTableCapacity - 1u; + + /// @brief Compact open-addressed 64-bit FNV-1a hash set (`512` slots = `4 KiB` on stack) for O(1) shadowed-entry + /// deduplication during multi-mount VFS directory iteration, replacing a `32 KiB` string array so recursive + /// VFS walks stay safely within `64 KiB` standard job-system fiber stacks (ADR-0049, ADR-0060). + struct MergedIterateState + { + SchemeBuffer scheme{}; + gp::PathBuffer baseRelativeDir{}; + gp::UInt64 seenHashes[kSeenTableCapacity]{}; + gp::USize seenCount{ 0u }; + MountPriority currentPriority{ MountPriority::Base }; + VfsDirectoryVisitorFn userVisitor{ nullptr }; + void* userContext{ nullptr }; + bool stopped{ false }; + + /// @brief Computes a non-zero 64-bit FNV-1a hash of a leaf filename for O(1) deduplication. + /// @param[in] name Leaf filename view. + /// @return Non-zero 64-bit hash (`0ULL` is reserved for empty table slots). + [[nodiscard]] static gp::UInt64 hashLeafName(const gp::StringView name) noexcept + { + gp::hashing::Fnv1a64 hasher{}; + hasher.update(name.data(), name.size()); + const gp::UInt64 digest = hasher.finalize(); + return (digest == 0ULL) ? 1ULL : digest; + } + + /// @brief Checks whether `name` was already emitted by a higher-priority layer and inserts it if unseen. + /// @param[in] name Leaf filename view. + /// @return True if `name` is newly inserted (caller should emit); false if already seen (caller skips). + [[nodiscard]] bool tryInsertSeen(const gp::StringView name) noexcept + { + const gp::UInt64 h = hashLeafName(name); + gp::USize slot = static_cast(h) & kSeenTableMask; + for (gp::USize probe = 0u; probe < kSeenTableCapacity; ++probe) + { + const gp::UInt64 existing = seenHashes[slot]; + if (existing == h) + { + return false; + } + if (existing == 0ULL) + { + seenHashes[slot] = h; + ++seenCount; + return true; + } + slot = (slot + 1u) & kSeenTableMask; + } + return true; + } + }; + + MergedIterateState mergedState{}; + mergedState.scheme = parsed.value().scheme; + mergedState.baseRelativeDir = parsed.value().relativePath; + mergedState.userVisitor = visitor; + mergedState.userContext = userData; + + const gp::platform::DirectoryVisitorFn backendVisitor = + [](const gp::platform::DirectoryEntry& rawEntry, void* const rawCtx) -> gp::platform::DirectoryVisitControl + { + MergedIterateState* const st = static_cast(rawCtx); + + // Deduplicate shadowed entries already emitted by a higher-priority mount layer in O(1). + if (!st->tryInsertSeen(rawEntry.name)) + { + return gp::platform::DirectoryVisitControl::Continue; + } + + const gp::PathBuffer relChild = st->baseRelativeDir.isEmpty() + ? gp::PathBuffer(rawEntry.name) + : gp::platform::Paths::combine(st->baseRelativeDir.view(), rawEntry.name); + const gp::PathBuffer fullUri = detail::buildCanonicalUri(st->scheme.view(), relChild.view()); + + VfsDirectoryEntry vfsEntry{}; + vfsEntry.uri = fullUri.view(); + vfsEntry.name = rawEntry.name; + vfsEntry.stats = rawEntry.stats; + vfsEntry.sourcePriority = st->currentPriority; + vfsEntry.depth = 0u; + + const gp::platform::DirectoryVisitControl ctrl = st->userVisitor(vfsEntry, st->userContext); + if (ctrl == gp::platform::DirectoryVisitControl::Stop) + { + st->stopped = true; + return gp::platform::DirectoryVisitControl::Stop; + } + return gp::platform::DirectoryVisitControl::Continue; + }; + + bool anyDirectoryFound = false; + VfsError firstNonNotFoundError = VfsError::NotFound; + + for (gp::USize i = 0u; i < mountCount; ++i) + { + mergedState.currentPriority = activePriorities[i]; + const gp::Expected res = + activeBackends[i]->iterateDirectory(parsed.value().relativePath.view(), backendVisitor, &mergedState); + + if (res.hasValue()) + { + anyDirectoryFound = true; + if (mergedState.stopped) + { + break; + } + } + else if (res.error() == VfsError::NotDirectory) + { + // A higher-priority mount shadows this URI with a regular file (not a directory): stop immediately so + // lower-priority directories are not leaked behind a shadowing file. + if (!anyDirectoryFound) + { + return gp::makeUnexpected(VfsError::NotDirectory); + } + } + else if (res.error() != VfsError::NotFound && firstNonNotFoundError == VfsError::NotFound) + { + firstNonNotFoundError = res.error(); + } + } + + if (!anyDirectoryFound) + { + return gp::makeUnexpected(firstNonNotFoundError); + } + + return true; +} + +gp::Expected VirtualFileSystem::iterateDirectoryRecursive( + const gp::StringView directoryUri, const VfsDirectoryVisitorFn visitor, void* const userData +) noexcept +{ + bool stopped = false; + return detail::iterateDirectoryRecursiveInternal(directoryUri, visitor, userData, 0u, stopped); +} + +gp::Expected VirtualFileSystem::readBytesAt( + const gp::StringView uri, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead +) noexcept +{ + if (bytesToRead > 0u && outBuffer == nullptr) + { + return gp::makeUnexpected(VfsError::InvalidArgument); + } + + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + gp::USize sorted[kMaxMountPoints]{}; + const gp::USize count = detail::collectSortedMountsForSchemeUnlocked(state, parsed.value().scheme.view(), sorted); + if (count == 0u) + { + return gp::makeUnexpected(VfsError::SchemeNotMounted); + } + + VfsError lastErr = VfsError::NotFound; + for (gp::USize i = 0u; i < count; ++i) + { + IMountBackend* const backend = state.mounts[sorted[i]].backend; + if (!backend->exists(parsed.value().relativePath.view())) + { + continue; + } + + const gp::Expected readRes = + backend->readBytesAt(parsed.value().relativePath.view(), offset, outBuffer, bytesToRead); + if (readRes.hasValue()) + { + return readRes.value(); + } + lastErr = readRes.error(); + if (lastErr != VfsError::NotFound) + { + break; + } + } + + return gp::makeUnexpected(lastErr); +} + +gp::Expected VirtualFileSystem::readBytes( + const gp::StringView uri, void* const outBuffer, const gp::USize bufferCapacity +) noexcept +{ + return readBytesAt(uri, 0ULL, outBuffer, bufferCapacity); +} + +gp::Expected VirtualFileSystem::writeAllBytes( + const gp::StringView uri, const void* const data, const gp::USize sizeInBytes +) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->writeBytes(parsed.value().relativePath.view(), data, sizeInBytes, false); +} + +gp::Expected + VirtualFileSystem::writeAllText(const gp::StringView uri, const gp::StringView text) noexcept +{ + return writeAllBytes(uri, text.data(), text.size()); +} + +gp::Expected VirtualFileSystem::appendAllBytes( + const gp::StringView uri, const void* const data, const gp::USize sizeInBytes +) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->writeBytes(parsed.value().relativePath.view(), data, sizeInBytes, true); +} + +gp::Expected + VirtualFileSystem::appendAllText(const gp::StringView uri, const gp::StringView text) noexcept +{ + return appendAllBytes(uri, text.data(), text.size()); +} + +gp::Expected VirtualFileSystem::writeAtomic( + const gp::StringView uri, const void* const data, const gp::USize sizeInBytes +) noexcept +{ + const gp::Expected parsed = parseUri(uri); + if (!parsed.hasValue()) + { + return gp::makeUnexpected(parsed.error()); + } + if (parsed.value().isSchemeRoot()) + { + return gp::makeUnexpected(VfsError::IsDirectory); + } + + detail::VfsGlobalState& state = detail::getState(); + const gp::thread::SharedLock lock(state.mutex); + + VfsError err = VfsError::None; + IMountBackend* const writable = detail::findWritableBackendUnlocked(state, parsed.value().scheme.view(), err); + if (writable == nullptr) + { + return gp::makeUnexpected(err); + } + + return writable->writeAtomic(parsed.value().relativePath.view(), data, sizeInBytes); +} + +gp::Expected + VirtualFileSystem::writeAtomicText(const gp::StringView uri, const gp::StringView text) noexcept +{ + return writeAtomic(uri, text.data(), text.size()); +} + +namespace +{ + +/// @brief Maximum entries emitted by a single `vfs.Ls` console command invocation to avoid terminal flooding. +constexpr gp::USize kMaxConsoleLsEntries = 256u; + +gp::console::AutoConsoleCommand g_cmdVfsStatus( + "vfs.Status", + "Prints active VirtualFileSystem mount counts across the canonical ADR-0044 URI schemes.", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + gp::FixedString<383> line{}; + gp::log::formatTo( + line, + "VFS[total={}/{}] engine={} game={} user={} appdata={} cache={} temp={}", + VirtualFileSystem::getMountCount(), + kMaxMountPoints, + VirtualFileSystem::getMountCount(kEngineScheme), + VirtualFileSystem::getMountCount(kGameScheme), + VirtualFileSystem::getMountCount(kUserScheme), + VirtualFileSystem::getMountCount(kAppDataScheme), + VirtualFileSystem::getMountCount(kCacheScheme), + VirtualFileSystem::getMountCount(kTempScheme) + ); + args.writeLine(line.view()); +}, + gp::console::ConsoleVarFlags::None +); + +gp::console::AutoConsoleCommand g_cmdVfsMounts( + "vfs.Mounts", + "Lists active VFS mount points in lookup precedence order. Usage: vfs.Mounts [scheme]", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + const gp::StringView schemeFilter = (args.getArgCount() >= 1u) ? args.getArg(0u) : gp::StringView{}; + const gp::USize totalMatches = VirtualFileSystem::getMountCount(schemeFilter); + + gp::FixedString<511> line{}; + if (totalMatches == 0u) + { + if (schemeFilter.isEmpty()) + { + args.writeLine("VFS Mounts: none registered."); + } + else + { + gp::log::formatTo(line, "VFS Mounts: no mounts registered for '{}'.", schemeFilter); + args.writeLine(line.view()); + } + return; + } + + if (schemeFilter.isEmpty()) + { + gp::log::formatTo(line, "VFS Mounts ({} active):", totalMatches); + } + else + { + gp::log::formatTo(line, "VFS Mounts for '{}' ({} active):", schemeFilter, totalMatches); + } + args.writeLine(line.view()); + + gp::USize index = 0u; + VirtualFileSystem::enumerateMounts( + schemeFilter, + [&args, &index](const MountPointDesc& desc) noexcept -> bool + { + gp::FixedString<511> entryLine{}; + gp::log::formatTo( + entryLine, + " [{}] {} | prio={}({}) | access={} | root={}", + index, + desc.scheme.view(), + toString(desc.priority), + static_cast(desc.priority), + toString(desc.access), + desc.rootPath.view() + ); + args.writeLine(entryLine.view()); + ++index; + return true; + } + ); +}, + gp::console::ConsoleVarFlags::None +); + +gp::console::AutoConsoleCommand g_cmdVfsResolve( + "vfs.Resolve", + "Parses a logical VFS URI and resolves its read and writable physical OS paths. Usage: vfs.Resolve ", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + if (args.getArgCount() < 1u) + { + args.writeLine("Usage: vfs.Resolve (e.g., vfs.Resolve user://saves/slot01.sav)"); + return; + } + + const gp::StringView uri = args.getArg(0u); + const gp::Expected parsed = VirtualFileSystem::parseUri(uri); + gp::FixedString<511> line{}; + if (!parsed.hasValue()) + { + gp::log::formatTo(line, "Resolve '{}': error={}", uri, toString(parsed.error())); + args.writeLine(line.view()); + return; + } + + gp::log::formatTo(line, "Canonical: {}{}", parsed.value().scheme.view(), parsed.value().relativePath.view()); + args.writeLine(line.view()); + + const gp::Expected readRes = VirtualFileSystem::resolvePhysicalPath(uri); + line.clear(); + if (readRes.hasValue()) + { + gp::log::formatTo(line, " ReadPath : {}", readRes.value().view()); + } + else + { + gp::log::formatTo(line, " ReadPath : <{}>", toString(readRes.error())); + } + args.writeLine(line.view()); + + const gp::Expected writeRes = VirtualFileSystem::resolveWritablePhysicalPath(uri); + line.clear(); + if (writeRes.hasValue()) + { + gp::log::formatTo(line, " WritePath: {}", writeRes.value().view()); + } + else + { + gp::log::formatTo(line, " WritePath: <{}>", toString(writeRes.error())); + } + args.writeLine(line.view()); +}, + gp::console::ConsoleVarFlags::None +); + +gp::console::AutoConsoleCommand g_cmdVfsExists( + "vfs.Exists", + "Checks whether a logical VFS URI exists and reports whether it is a file or directory. Usage: vfs.Exists ", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + if (args.getArgCount() < 1u) + { + args.writeLine("Usage: vfs.Exists (e.g., vfs.Exists game://configs/default.ini)"); + return; + } + + const gp::StringView uri = args.getArg(0u); + const gp::Expected parsed = VirtualFileSystem::parseUri(uri); + gp::FixedString<511> line{}; + if (!parsed.hasValue()) + { + gp::log::formatTo(line, "Exists '{}': error={}", uri, toString(parsed.error())); + args.writeLine(line.view()); + return; + } + + if (!VirtualFileSystem::isSchemeMounted(parsed.value().scheme.view())) + { + gp::log::formatTo(line, "Exists '{}': error={}", uri, toString(VfsError::SchemeNotMounted)); + args.writeLine(line.view()); + return; + } + + const bool exists = VirtualFileSystem::exists(uri); + const bool isFile = exists && VirtualFileSystem::isFile(uri); + const bool isDir = exists && VirtualFileSystem::isDirectory(uri); + gp::log::formatTo(line, "Exists '{}': exists={} isFile={} isDirectory={}", uri, exists, isFile, isDir); + args.writeLine(line.view()); +}, + gp::console::ConsoleVarFlags::None +); + +gp::console::AutoConsoleCommand g_cmdVfsStat( + "vfs.Stat", + "Prints size, attributes, and timestamps for a logical VFS URI. Usage: vfs.Stat ", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + if (args.getArgCount() < 1u) + { + args.writeLine("Usage: vfs.Stat (e.g., vfs.Stat user://saves/slot01.sav)"); + return; + } + + const gp::StringView uri = args.getArg(0u); + const gp::Expected statRes = VirtualFileSystem::getStats(uri); + gp::FixedString<511> line{}; + if (!statRes.hasValue()) + { + gp::log::formatTo(line, "Stat '{}': error={}", uri, toString(statRes.error())); + args.writeLine(line.view()); + return; + } + + const gp::platform::FileStats& stats = statRes.value(); + const gp::StringView typeStr = stats.isDirectory() ? "Directory" : (stats.isFile() ? "File" : "Other"); + gp::log::formatTo( + line, + "Stat '{}': type={} size={}B readOnly={} hidden={} symLink={} createdNs={} modifiedNs={} accessedNs={}", + uri, + typeStr, + stats.size, + stats.isReadOnly(), + stats.isHidden(), + stats.isSymbolicLink(), + stats.creationTime.nanoseconds, + stats.lastWriteTime.nanoseconds, + stats.lastAccessTime.nanoseconds + ); + args.writeLine(line.view()); +}, + gp::console::ConsoleVarFlags::None +); + +gp::console::AutoConsoleCommand g_cmdVfsLs( + "vfs.Ls", + "Lists merged VFS directory entries in overlay priority order. Usage: vfs.Ls [-r]", + [](const gp::console::ConsoleCommandArgs& args) noexcept -> void +{ + if (args.getArgCount() < 1u) + { + args.writeLine("Usage: vfs.Ls [-r] (e.g., vfs.Ls game:// -r)"); + return; + } + + const gp::StringView uri = args.getArg(0u); + bool recursive = false; + if (args.getArgCount() >= 2u) + { + const gp::StringView flag = args.getArg(1u); + recursive = flag.equalsIgnoreCase("-r") || flag.equalsIgnoreCase("--recursive"); + } + + gp::USize printedCount = 0u; + bool truncated = false; + const auto visitor = [&args, + &printedCount, + &truncated](const VfsDirectoryEntry& entry) noexcept -> gp::platform::DirectoryVisitControl + { + if (printedCount >= kMaxConsoleLsEntries) + { + truncated = true; + return gp::platform::DirectoryVisitControl::Stop; + } + + const gp::StringView kindTag = entry.isDirectory() ? "[DIR ]" : "[FILE]"; + gp::FixedString<511> entryLine{}; + gp::log::formatTo( + entryLine, + " {} {:10}B | prio={} | {}", + kindTag, + entry.stats.size, + toString(entry.sourcePriority), + entry.uri + ); + args.writeLine(entryLine.view()); + ++printedCount; + return gp::platform::DirectoryVisitControl::Continue; + }; + + const gp::Expected iterRes = recursive ? VirtualFileSystem::iterateDirectoryRecursive(uri, visitor) + : VirtualFileSystem::iterateDirectory(uri, visitor); + gp::FixedString<511> summary{}; + if (!iterRes.hasValue()) + { + gp::log::formatTo(summary, "Ls '{}': error={}", uri, toString(iterRes.error())); + args.writeLine(summary.view()); + return; + } + + if (truncated) + { + gp::log::formatTo(summary, "... (truncated at {} entries)", kMaxConsoleLsEntries); + } + else + { + gp::log::formatTo(summary, "Total: {} entries", printedCount); + } + args.writeLine(summary.view()); +}, + gp::console::ConsoleVarFlags::None +); + +} // namespace + +} // namespace gp::vfs diff --git a/source/runtime/core/public/logging/sinks/FileSink.hpp b/source/runtime/core/public/logging/sinks/FileSink.hpp index 294ee307..8939578c 100644 --- a/source/runtime/core/public/logging/sinks/FileSink.hpp +++ b/source/runtime/core/public/logging/sinks/FileSink.hpp @@ -9,15 +9,18 @@ #include "logging/ILogSink.hpp" #include "logging/LogDesc.hpp" #include "logging/LogEnums.hpp" +#include "platforms/base/system/FileHandle.hpp" #include "platforms/base/system/PathTypes.hpp" namespace gp::log { -/// @brief Buffered, zero-heap-allocation file output sink backed by `gp::platform::Paths` ([ADR-0054]). +/// @brief Buffered, zero-heap-allocation file output sink backed by `gp::platform::FileHandle` and +/// `gp::platform::Paths` ([ADR-0054], [ADR-0060]). /// @details Accumulates formatted log lines inside an inline `8 KiB` write buffer (`m_writeBuffer`) to minimize OS /// write syscalls, flushing automatically when the buffer fills, when `record.level >= LogLevel::Error`, or -/// when `flush()` / `close()` is called. +/// when `flush()` / `close()` is called. Opens the underlying handle with `FileShareMode::Read` so external +/// log viewers can inspect live logs while the engine is running. class GP_CORE_API FileSink final : public ILogSink { public: @@ -25,7 +28,7 @@ class GP_CORE_API FileSink final : public ILogSink static constexpr gp::USize kWriteBufferCapacity = 8192u; private: - void* m_fileHandle{ nullptr }; + gp::platform::FileHandle m_fileHandle{}; gp::platform::PathBuffer m_filePath{}; LogSinkFlags m_flags{ LogSinkFlags::DefaultTextFormat | LogSinkFlags::IncludeSourceLocation }; gp::USize m_bufferedBytes{ 0u }; @@ -46,18 +49,20 @@ class GP_CORE_API FileSink final : public ILogSink public: /// @brief Opens (or re-opens) the target log file specified in `desc`. /// @details If `desc.filePath` is empty, resolves `/.log` via `gp::platform::Paths`. + /// Creates missing parent directories automatically before opening the OS file handle. /// @param[in] desc File sink configuration parameters. - /// @return `LogResult::Success` if the file was opened, or `LogResult::IoError` on failure. + /// @return `LogResult::Success` if the file was opened, `LogResult::InvalidArguments` if the resolved path is + /// empty, or `LogResult::IoError` on OS open failure. [[nodiscard]] LogResult open(const FileSinkDesc& desc) noexcept; - /// @brief Flushes any buffered output and closes the underlying file handle. + /// @brief Flushes any buffered output and closes the underlying OS `FileHandle`. void close() noexcept; /// @brief Checks whether the log file is currently open for writing. /// @return True if open, false otherwise. - [[nodiscard]] constexpr bool isOpen() const noexcept + [[nodiscard]] bool isOpen() const noexcept { - return m_fileHandle != nullptr; + return m_fileHandle.isValid(); } /// @brief Queries the normalized filesystem path of the opened log file. diff --git a/source/runtime/core/public/platforms/apple/system/AppleFileSystem.hpp b/source/runtime/core/public/platforms/apple/system/AppleFileSystem.hpp new file mode 100644 index 00000000..19fde008 --- /dev/null +++ b/source/runtime/core/public/platforms/apple/system/AppleFileSystem.hpp @@ -0,0 +1,20 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/unix/system/UnixFileSystem.hpp" + +namespace gp::platform::apple +{ + +/// @brief Apple (Darwin / macOS / iOS) implementation of Layer 0 OS file and directory utilities (ADR-0060). +class GP_CORE_API FileSystem : public gp::platform::unix::FileSystem +{ +public: + FileSystem() = delete; +}; + +} // namespace gp::platform::apple diff --git a/source/runtime/core/public/platforms/base/system/FileEnums.hpp b/source/runtime/core/public/platforms/base/system/FileEnums.hpp new file mode 100644 index 00000000..145bcfa5 --- /dev/null +++ b/source/runtime/core/public/platforms/base/system/FileEnums.hpp @@ -0,0 +1,227 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "templates/Enums.hpp" + +namespace gp::platform +{ + +/// @brief Explicit diagnostic error codes returned by Layer 0 `gp::platform::FileSystem` and `FileHandle` (ADR-0060). +enum class FileError : gp::UInt8 +{ + /// @brief Operation completed without error. + None = 0, + + /// @brief The requested file or directory does not exist on the filesystem. + NotFound = 1, + + /// @brief The target file or directory already exists when an exclusive creation mode was requested. + AlreadyExists = 2, + + /// @brief The operating system denied access due to read-only flags, file locks, or insufficient privileges. + AccessDenied = 3, + + /// @brief The supplied path is empty, exceeds `kMaxPathLength`, or fails lexical validation. + InvalidPath = 4, + + /// @brief An invalid parameter (e.g., null buffer with non-zero size or unaligned/negative offset) was provided. + InvalidArgument = 5, + + /// @brief The `FileHandle` is closed or holds an invalid native OS descriptor. + InvalidHandle = 6, + + /// @brief A directory was encountered where a regular file was expected (e.g., `openRead` on a folder). + IsDirectory = 7, + + /// @brief A regular file was encountered where a directory was expected (e.g., `iterateDirectory` on a file). + NotDirectory = 8, + + /// @brief Attempted to remove a directory that still contains child files or subdirectories. + DirectoryNotEmpty = 9, + + /// @brief The destination storage volume has insufficient free space to complete the write. + DiskFull = 10, + + /// @brief The file is currently locked or opened with incompatible sharing flags by another process or handle. + SharingViolation = 11, + + /// @brief The process or system has reached its maximum open file descriptor limit (`EMFILE` / `ENFILE`). + TooManyOpenFiles = 12, + + /// @brief Attempted to perform an atomic rename across distinct physical volumes/mount points (`EXDEV`). + CrossDeviceLink = 13, + + /// @brief Directory recursion depth exceeded `kMaxDirectoryRecursionDepth` (`32`). + MaxRecursionDepthExceeded = 14, + + /// @brief The target filesystem or mount point is read-only (`EROFS`). + ReadOnlyFileSystem = 15, + + /// @brief A hardware, driver, or kernel I/O transfer failure occurred (`EIO`). + IoFailure = 16, + + /// @brief The operation is not supported on the current platform or fallback backend. + NotSupported = 17 +}; + +/// @brief Read/write permission modes requested when opening an OS `FileHandle` (ADR-0060). +enum class FileAccessMode : gp::UInt8 +{ + /// @brief Open the file strictly for reading (`GENERIC_READ` / `O_RDONLY`). + Read = 0x01, + + /// @brief Open the file strictly for writing (`GENERIC_WRITE` / `O_WRONLY`). + Write = 0x02, + + /// @brief Open the file for both reading and writing (`GENERIC_READ | GENERIC_WRITE` / `O_RDWR`). + ReadWrite = Read | Write +}; + +/// @brief Creation and truncation disposition when opening an OS `FileHandle` (ADR-0060). +enum class FileOpenMode : gp::UInt8 +{ + /// @brief Opens an existing file; fails with `FileError::NotFound` if the file does not exist (`OPEN_EXISTING`). + OpenExisting = 0, + + /// @brief Creates a new file or truncates an existing file to zero bytes (`CREATE_ALWAYS` / `O_CREAT | O_TRUNC`). + CreateAlways = 1, + + /// @brief Creates a new file; fails with `FileError::AlreadyExists` if it already exists (`CREATE_NEW` / `O_EXCL`). + CreateNew = 2, + + /// @brief Opens the file if it exists or creates a new file if it does not (`OPEN_ALWAYS` / `O_CREAT`). + OpenAlways = 3, + + /// @brief Opens or creates a file and positions all sequential writes at the end (`O_CREAT | O_APPEND`). + Append = 4 +}; + +/// @brief Concurrent access sharing flags granted to other handles while a `FileHandle` is open (ADR-0060). +enum class FileShareMode : gp::UInt8 +{ + /// @brief Exclusive access: prevents other openers from reading, writing, or deleting the file. + None = 0x00, + + /// @brief Allows other handles to read the file concurrently (`FILE_SHARE_READ`). + Read = 0x01, + + /// @brief Allows other handles to write to the file concurrently (`FILE_SHARE_WRITE`). + Write = 0x02, + + /// @brief Allows other handles to delete or rename the file while open (`FILE_SHARE_DELETE`). + Delete = 0x04, + + /// @brief Default read-write sharing mask (`Read | Write`). + ReadWrite = Read | Write, + + /// @brief Full POSIX-like sharing semantics (`Read | Write | Delete`). + All = Read | Write | Delete +}; + +/// @brief Reference origin for `FileHandle::seek()` cursor repositioning (ADR-0060). +enum class FileSeekOrigin : gp::UInt8 +{ + /// @brief Offset is measured relative to the beginning of the file (`FILE_BEGIN` / `SEEK_SET`). + Begin = 0, + + /// @brief Offset is measured relative to the current cursor position (`FILE_CURRENT` / `SEEK_CUR`). + Current = 1, + + /// @brief Offset is measured relative to the end of the file (`FILE_END` / `SEEK_END`). + End = 2 +}; + +/// @brief Bitmask attributes describing a filesystem entry in `FileStats` (ADR-0060). +enum class FileAttributeFlags : gp::UInt8 +{ + /// @brief No valid attributes (or entry does not exist). + None = 0x00, + + /// @brief Entry is a standard data file. + RegularFile = 0x01, + + /// @brief Entry is a directory/folder. + Directory = 0x02, + + /// @brief Entry is marked read-only (writes and deletions without attribute clearing will fail). + ReadOnly = 0x04, + + /// @brief Entry is marked hidden (Win32 `FILE_ATTRIBUTE_HIDDEN` or dot-prefixed `".name"` on POSIX). + Hidden = 0x08, + + /// @brief Entry is a symbolic link or NTFS reparse point. + SymbolicLink = 0x10 +}; + +/// @brief Flow control directive returned by directory iteration callbacks (ADR-0060). +enum class DirectoryVisitControl : gp::UInt8 +{ + /// @brief Continue visiting remaining entries (and descend into subdirectories during recursive traversal). + Continue = 0, + + /// @brief During `iterateDirectoryRecursive`, do not descend into the current directory entry, but continue + /// siblings. + SkipSubdirectory = 1, + + /// @brief Immediately terminate directory traversal and return success to the caller. + Stop = 2 +}; + +/// @brief Returns a human-readable ASCII name for a `FileError` enum value (for diagnostics and logging). +/// @param[in] error The `FileError` value to stringify. +/// @return Null-terminated static string view naming the error code. +[[nodiscard]] constexpr gp::StringView toString(const FileError error) noexcept +{ + switch (error) + { + case FileError::None: + return "None"; + case FileError::NotFound: + return "NotFound"; + case FileError::AlreadyExists: + return "AlreadyExists"; + case FileError::AccessDenied: + return "AccessDenied"; + case FileError::InvalidPath: + return "InvalidPath"; + case FileError::InvalidArgument: + return "InvalidArgument"; + case FileError::InvalidHandle: + return "InvalidHandle"; + case FileError::IsDirectory: + return "IsDirectory"; + case FileError::NotDirectory: + return "NotDirectory"; + case FileError::DirectoryNotEmpty: + return "DirectoryNotEmpty"; + case FileError::DiskFull: + return "DiskFull"; + case FileError::SharingViolation: + return "SharingViolation"; + case FileError::TooManyOpenFiles: + return "TooManyOpenFiles"; + case FileError::CrossDeviceLink: + return "CrossDeviceLink"; + case FileError::MaxRecursionDepthExceeded: + return "MaxRecursionDepthExceeded"; + case FileError::ReadOnlyFileSystem: + return "ReadOnlyFileSystem"; + case FileError::IoFailure: + return "IoFailure"; + case FileError::NotSupported: + return "NotSupported"; + default: + return "Unknown"; + } +} + +} // namespace gp::platform + +GP_ENABLE_ENUM_BITWISE_OPERATIONS(gp::platform::FileAccessMode); +GP_ENABLE_ENUM_BITWISE_OPERATIONS(gp::platform::FileShareMode); +GP_ENABLE_ENUM_BITWISE_OPERATIONS(gp::platform::FileAttributeFlags); diff --git a/source/runtime/core/public/platforms/base/system/FileHandle.hpp b/source/runtime/core/public/platforms/base/system/FileHandle.hpp new file mode 100644 index 00000000..de5f62be --- /dev/null +++ b/source/runtime/core/public/platforms/base/system/FileHandle.hpp @@ -0,0 +1,164 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileTypes.hpp" +#include "templates/Expected.hpp" + +namespace gp::platform +{ + +/// @brief Non-polymorphic, zero-allocation RAII operating system file handle (ADR-0060). +/// @details Wraps a native OS descriptor (`HANDLE` on Windows, `int fd` on POSIX) directly in an 8-byte value type +/// with zero heap allocations and zero virtual dispatch overhead. Exposes both sequential cursor I/O +/// (`read`, `write`, `seek`, `tell`) and lock-free positional I/O (`readAt`, `writeAt` via Win32 `OVERLAPPED` +/// offsets and POSIX `pread`/`pwrite`) so multiple worker fibers can stream disjoint chunks from a single +/// open handle concurrently without mutex contention. +class GP_CORE_API FileHandle final +{ +public: + /// @brief Default-constructs an unopened, invalid `FileHandle`. + [[nodiscard]] FileHandle() noexcept = default; + + /// @brief Constructs a `FileHandle` taking ownership of an open `NativeFileDescriptor`. + /// @param[in] descriptor Raw OS file handle/descriptor to adopt. + [[nodiscard]] explicit FileHandle(const NativeFileDescriptor descriptor) noexcept + : m_descriptor(descriptor) + {} + + /// @brief Destructor. Automatically closes the underlying OS file descriptor if valid. + ~FileHandle() noexcept + { + if (isValid()) + { + close(); + } + } + + FileHandle(const FileHandle&) = delete; + FileHandle& operator=(const FileHandle&) = delete; + + /// @brief Move constructor. Transfers ownership of the native OS file descriptor from `other`. + /// @param[in,out] other Source handle to move from; left in a closed (`kInvalidNativeFileDescriptor`) state. + [[nodiscard]] FileHandle(FileHandle&& other) noexcept + : m_descriptor(other.m_descriptor) + { + other.m_descriptor = kInvalidNativeFileDescriptor; + } + + /// @brief Move assignment operator. Closes any currently held descriptor and adopts `other`'s descriptor. + /// @param[in,out] other Source handle to move from; left in a closed state. + /// @return Reference to `*this`. + FileHandle& operator=(FileHandle&& other) noexcept + { + if (this != &other) + { + if (isValid()) + { + close(); + } + m_descriptor = other.m_descriptor; + other.m_descriptor = kInvalidNativeFileDescriptor; + } + return *this; + } + +public: + /// @brief Checks whether this handle currently owns an open native OS file descriptor. + /// @return True if the descriptor is valid (`!= kInvalidNativeFileDescriptor`), false otherwise. + [[nodiscard]] bool isValid() const noexcept + { + return m_descriptor != kInvalidNativeFileDescriptor; + } + + /// @brief Boolean conversion operator returning `isValid()`. + /// @return True if open and valid, false otherwise. + [[nodiscard]] explicit operator bool() const noexcept + { + return isValid(); + } + + /// @brief Returns the underlying native OS file descriptor without releasing ownership. + /// @return `NativeFileDescriptor` (`HANDLE` on Windows, `Int32` fd on POSIX). + [[nodiscard]] NativeFileDescriptor nativeDescriptor() const noexcept + { + return m_descriptor; + } + + /// @brief Releases ownership of the underlying native OS file descriptor without closing it. + /// @return The previously held `NativeFileDescriptor`. + [[nodiscard]] NativeFileDescriptor release() noexcept + { + const NativeFileDescriptor raw = m_descriptor; + m_descriptor = kInvalidNativeFileDescriptor; + return raw; + } + + /// @brief Explicitly closes the underlying OS file descriptor. + /// @return `Expected` containing `true` on success (or if already closed), or a `FileError`. + gp::Expected close() noexcept; + + /// @brief Reads up to `bytesToRead` bytes sequentially from the current file cursor into `outBuffer`. + /// @param[out] outBuffer Destination memory buffer (must be non-null if `bytesToRead > 0`). + /// @param[in] bytesToRead Maximum number of bytes to read. + /// @return `Expected` containing the number of bytes actually read (`0` at EOF), or error. + [[nodiscard]] gp::Expected read(void* const outBuffer, const gp::USize bytesToRead) noexcept; + + /// @brief Writes `bytesToWrite` bytes sequentially at the current file cursor from `buffer`. + /// @param[in] buffer Source memory buffer (must be non-null if `bytesToWrite > 0`). + /// @param[in] bytesToWrite Number of bytes to write. + /// @return `Expected` containing the total bytes written, or a `FileError`. + [[nodiscard]] gp::Expected + write(const void* const buffer, const gp::USize bytesToWrite) noexcept; + + /// @brief Performs a thread-safe positional read at an explicit 64-bit byte offset (`OVERLAPPED` / `pread`). + /// @note Does not require an external mutex when multiple worker fibers read disjoint byte ranges from the same + /// open `FileHandle` concurrently (ADR-0060). + /// @param[in] offset Absolute byte offset from the beginning of the file. + /// @param[out] outBuffer Destination memory buffer (must be non-null if `bytesToRead > 0`). + /// @param[in] bytesToRead Maximum number of bytes to read. + /// @return `Expected` containing the number of bytes actually read (`0` at/past EOF). + [[nodiscard]] gp::Expected + readAt(const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead) const noexcept; + + /// @brief Performs a positional write at an explicit 64-bit byte offset (`OVERLAPPED` / `pwrite`). + /// @param[in] offset Absolute byte offset from the beginning of the file. + /// @param[in] buffer Source memory buffer (must be non-null if `bytesToWrite > 0`). + /// @param[in] bytesToWrite Number of bytes to write. + /// @return `Expected` containing the total bytes written, or a `FileError`. + [[nodiscard]] gp::Expected + writeAt(const gp::UInt64 offset, const void* const buffer, const gp::USize bytesToWrite) noexcept; + + /// @brief Repositions the sequential file cursor relative to `origin`. + /// @param[in] offset Signed byte offset relative to `origin`. + /// @param[in] origin Reference point (`FileSeekOrigin::Begin`, `Current`, or `End`). + /// @return `Expected` containing the new absolute byte offset from the start of the file. + [[nodiscard]] gp::Expected + seek(const gp::Int64 offset, const FileSeekOrigin origin = FileSeekOrigin::Begin) noexcept; + + /// @brief Queries the current sequential file cursor offset from the beginning of the file. + /// @return `Expected` containing the current byte position. + [[nodiscard]] gp::Expected tell() const noexcept; + + /// @brief Queries the current logical byte size of the open file. + /// @return `Expected` containing the total file size in bytes. + [[nodiscard]] gp::Expected size() const noexcept; + + /// @brief Flushes any buffered kernel pages for this file to non-volatile storage (`FlushFileBuffers` / `fsync`). + /// @return `Expected` containing `true` on success, or a `FileError`. + gp::Expected flush() noexcept; + + /// @brief Resizes (truncates or extends) the open file to `newSize` bytes (`SetEndOfFile` / `ftruncate`). + /// @param[in] newSize Target file size in bytes. + /// @return `Expected` containing `true` on success, or a `FileError`. + gp::Expected truncate(const gp::UInt64 newSize) noexcept; + +private: + NativeFileDescriptor m_descriptor{ kInvalidNativeFileDescriptor }; +}; + +} // namespace gp::platform diff --git a/source/runtime/core/public/platforms/base/system/FileSystem.hpp b/source/runtime/core/public/platforms/base/system/FileSystem.hpp new file mode 100644 index 00000000..dac2a745 --- /dev/null +++ b/source/runtime/core/public/platforms/base/system/FileSystem.hpp @@ -0,0 +1,43 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "platforms/base/Platform.hpp" // IWYU pragma: keep +#include "platforms/base/system/FileEnums.hpp" // IWYU pragma: export +#include "platforms/base/system/FileHandle.hpp" // IWYU pragma: export +#include "platforms/base/system/FileTypes.hpp" // IWYU pragma: export + +#if GP_PLATFORM_WINDOWS + #include "platforms/windows/system/WindowsFileSystem.hpp" +#elif GP_PLATFORM_LINUX + #include "platforms/linux/system/LinuxFileSystem.hpp" +#elif GP_PLATFORM_MACOS + #include "platforms/macos/system/MacOSFileSystem.hpp" +#elif GP_PLATFORM_APPLE + #include "platforms/apple/system/AppleFileSystem.hpp" +#elif GP_PLATFORM_UNIX + #include "platforms/unix/system/UnixFileSystem.hpp" +#else + #include "platforms/generic/system/GenericFileSystem.hpp" +#endif + +namespace gp::platform +{ + +#if GP_PLATFORM_WINDOWS +using FileSystem = gp::platform::windows::FileSystem; +#elif GP_PLATFORM_LINUX +using FileSystem = gp::platform::linux::FileSystem; +#elif GP_PLATFORM_MACOS +using FileSystem = gp::platform::macos::FileSystem; +#elif GP_PLATFORM_APPLE +using FileSystem = gp::platform::apple::FileSystem; +#elif GP_PLATFORM_UNIX +using FileSystem = gp::platform::unix::FileSystem; +#else +using FileSystem = gp::platform::generic::FileSystem; +#endif + +} // namespace gp::platform diff --git a/source/runtime/core/public/platforms/base/system/FileTypes.hpp b/source/runtime/core/public/platforms/base/system/FileTypes.hpp new file mode 100644 index 00000000..4d37f396 --- /dev/null +++ b/source/runtime/core/public/platforms/base/system/FileTypes.hpp @@ -0,0 +1,142 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/Platform.hpp" // IWYU pragma: keep +#include "platforms/base/system/FileEnums.hpp" +#include "templates/Enums.hpp" +#include "time/TimeTypes.hpp" + +namespace gp::platform +{ + +/// @brief Maximum nested subdirectory depth permitted during stack-buffered recursive directory traversal (ADR-0060). +/// @details Bounded to `32` levels (~35 KiB maximum stack footprint across recursive `PathBuffer` frames) so recursive +/// directory queries remain safe inside `64 KiB` standard job-system fibers (ADR-0049). +inline constexpr gp::UInt32 kMaxDirectoryRecursionDepth = 32u; + +/// @brief Default stack chunk buffer size (`16 KiB`) used by `FileSystem::copyFile` fallback streaming. +inline constexpr gp::USize kFileCopyChunkSize = 16384u; + +#if GP_PLATFORM_WINDOWS +/// @brief Native operating system file handle representation (`void*` Win32 `HANDLE`). +using NativeFileDescriptor = void*; + +/// @brief Sentinel value representing an unopened or closed Win32 `HANDLE` (`INVALID_HANDLE_VALUE`). +inline const NativeFileDescriptor kInvalidNativeFileDescriptor = reinterpret_cast(static_cast(-1)); +#else +/// @brief Native operating system file handle representation (`gp::Int32` POSIX file descriptor). +using NativeFileDescriptor = gp::Int32; + +/// @brief Sentinel value representing an unopened or closed POSIX file descriptor (`-1`). +inline constexpr NativeFileDescriptor kInvalidNativeFileDescriptor = -1; +#endif + +/// @brief Plain-Old-Data (POD) metadata snapshot for a file or directory on disk (ADR-0060). +struct FileStats +{ +public: + /// @brief Logical size of the file in bytes (`0` for directories). + gp::UInt64 size{ 0ULL }; + + /// @brief Creation (birth) time in UTC nanoseconds since the Unix Epoch (`1970-01-01T00:00:00Z`). + /// @note On POSIX filesystems where birth time is unavailable, falls back to `lastWriteTime`. + gp::time::Timestamp creationTime{}; + + /// @brief Last content modification time in UTC nanoseconds since the Unix Epoch (`1970-01-01T00:00:00Z`). + gp::time::Timestamp lastWriteTime{}; + + /// @brief Last access time in UTC nanoseconds since the Unix Epoch (`1970-01-01T00:00:00Z`). + gp::time::Timestamp lastAccessTime{}; + + /// @brief Bitmask of `FileAttributeFlags` (`RegularFile`, `Directory`, `ReadOnly`, `Hidden`, `SymbolicLink`). + FileAttributeFlags attributes{ FileAttributeFlags::None }; + +public: + /// @brief Checks whether this metadata snapshot represents a regular data file. + /// @return True if `FileAttributeFlags::RegularFile` is set, false otherwise. + [[nodiscard]] constexpr bool isFile() const noexcept + { + return gp::enums::hasAllFlags(attributes, FileAttributeFlags::RegularFile); + } + + /// @brief Checks whether this metadata snapshot represents a directory. + /// @return True if `FileAttributeFlags::Directory` is set, false otherwise. + [[nodiscard]] constexpr bool isDirectory() const noexcept + { + return gp::enums::hasAllFlags(attributes, FileAttributeFlags::Directory); + } + + /// @brief Checks whether this entry is marked read-only. + /// @return True if `FileAttributeFlags::ReadOnly` is set, false otherwise. + [[nodiscard]] constexpr bool isReadOnly() const noexcept + { + return gp::enums::hasAllFlags(attributes, FileAttributeFlags::ReadOnly); + } + + /// @brief Checks whether this entry is marked hidden. + /// @return True if `FileAttributeFlags::Hidden` is set, false otherwise. + [[nodiscard]] constexpr bool isHidden() const noexcept + { + return gp::enums::hasAllFlags(attributes, FileAttributeFlags::Hidden); + } + + /// @brief Checks whether this entry is a symbolic link or reparse point. + /// @return True if `FileAttributeFlags::SymbolicLink` is set, false otherwise. + [[nodiscard]] constexpr bool isSymbolicLink() const noexcept + { + return gp::enums::hasAllFlags(attributes, FileAttributeFlags::SymbolicLink); + } + + /// @brief Compares two `FileStats` instances for exact equality. + /// @param[in] other The stats struct to compare against. + /// @return True if all fields match, false otherwise. + [[nodiscard]] constexpr bool operator==(const FileStats& other) const noexcept = default; +}; + +/// @brief Non-owning stack view passed to directory iteration visitors during `FileSystem::iterateDirectory` +/// (ADR-0060). +/// @note Both `path` and `name` point directly into the active stack `PathBuffer` of the iteration frame. Callers that +/// wish to retain paths after the visitor callback returns must copy them into a `PathBuffer` or `gp::String`. +struct DirectoryEntry +{ +public: + /// @brief Normalized full or relative path to the entry (e.g., `"C:/Dir/Sub/File.txt"`, no trailing slash). + gp::StringView path{}; + + /// @brief Clean leaf filename or directory name without parent path components (e.g., `"File.txt"` or `"Sub"`). + gp::StringView name{}; + + /// @brief Pre-populated metadata snapshot for the entry (size, timestamps, and `FileAttributeFlags`). + FileStats stats{}; + + /// @brief Zero-based recursion depth relative to the root directory passed to `iterateDirectoryRecursive`. + gp::UInt32 depth{ 0u }; + +public: + /// @brief Convenience check returning true if this directory entry is a regular file. + /// @return True if `stats.isFile()`, false otherwise. + [[nodiscard]] constexpr bool isFile() const noexcept + { + return stats.isFile(); + } + + /// @brief Convenience check returning true if this directory entry is a subdirectory. + /// @return True if `stats.isDirectory()`, false otherwise. + [[nodiscard]] constexpr bool isDirectory() const noexcept + { + return stats.isDirectory(); + } +}; + +/// @brief Stateless C-style callback signature for zero-allocation directory iteration (ADR-0060). +/// @param[in] entry Stack-resident directory entry descriptor for the current item. +/// @param[in] userData Opaque caller-supplied context pointer. +/// @return `DirectoryVisitControl` instructing the iterator to `Continue`, `SkipSubdirectory`, or `Stop`. +using DirectoryVisitorFn = DirectoryVisitControl (*)(const DirectoryEntry& entry, void* userData); + +} // namespace gp::platform diff --git a/source/runtime/core/public/platforms/base/system/PathTypes.hpp b/source/runtime/core/public/platforms/base/system/PathTypes.hpp index fe614114..e05bb1a6 100644 --- a/source/runtime/core/public/platforms/base/system/PathTypes.hpp +++ b/source/runtime/core/public/platforms/base/system/PathTypes.hpp @@ -5,7 +5,7 @@ #pragma once #include "containers/strings/FixedString.hpp" -#include "containers/views/StringView.hpp" +#include "containers/views/StringView.hpp" // IWYU pragma: keep #include "CoreMinimal.hpp" namespace gp::platform diff --git a/source/runtime/core/public/platforms/generic/system/GenericFileSystem.hpp b/source/runtime/core/public/platforms/generic/system/GenericFileSystem.hpp new file mode 100644 index 00000000..56fbafcf --- /dev/null +++ b/source/runtime/core/public/platforms/generic/system/GenericFileSystem.hpp @@ -0,0 +1,800 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/strings/String.hpp" +#include "containers/views/StringView.hpp" +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileHandle.hpp" +#include "platforms/base/system/FileTypes.hpp" +#include "platforms/base/system/Paths.hpp" +#include "templates/Expected.hpp" +#include "threading/atomics/Atomic.hpp" +#include +#include + +namespace gp::platform::generic +{ + +/// @brief Base contract and portable composite algorithms for Layer 0 OS file and directory utilities (ADR-0060). +/// @details Derived platform classes (`windows::FileSystem`, `unix::FileSystem`, `linux::FileSystem`, +/// `apple::FileSystem`, `macos::FileSystem`) implement the low-level OS syscalls (`open`, `getStats`, +/// `createDirectory`, `removeFile`, `removeDirectory`, `move`, `setReadOnly`, `iterateDirectory`) and inherit +/// portable recursive directory creation/deletion, chunked file copying, bulk file reading/writing, and +/// crash-safe atomic write transactions (`writeAtomic`). +class GP_CORE_API FileSystem +{ +public: + FileSystem() = delete; + ~FileSystem() = delete; + FileSystem(const FileSystem&) = delete; + FileSystem& operator=(const FileSystem&) = delete; + FileSystem(FileSystem&&) = delete; + FileSystem& operator=(FileSystem&&) = delete; + +public: + /// @section File Handle Creation (Base Fallback Contract) + + /// @brief Opens a native OS `FileHandle` with explicit access, creation disposition, and sharing modes. + /// @param[in] path Physical UTF-8 filesystem path to open. + /// @param[in] access Read/Write access flags (`FileAccessMode::Read`, `Write`, or `ReadWrite`). + /// @param[in] openMode Creation/truncation disposition (`OpenExisting`, `CreateAlways`, `CreateNew`, etc.). + /// @param[in] shareMode Concurrent handle sharing flags (`FileShareMode::Read`, `ReadWrite`, `All`, `None`). + /// @return `Expected` containing the open RAII handle on success, or a `FileError`. + [[nodiscard]] static gp::Expected open( + const gp::StringView path, + const FileAccessMode access, + const FileOpenMode openMode, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + + /// @brief Convenience helper opening an existing file strictly for reading (`OpenExisting`, `Share::ReadWrite`). + /// @param[in] path Physical UTF-8 filesystem path to open. + /// @param[in] shareMode Concurrent sharing permissions (defaults to `FileShareMode::ReadWrite`). + /// @return `Expected` containing the open read-only `FileHandle`. + [[nodiscard]] static gp::Expected + openRead(const gp::StringView path, const FileShareMode shareMode = FileShareMode::ReadWrite) noexcept; + + /// @brief Convenience helper opening or creating a file for writing. + /// @param[in] path Physical UTF-8 filesystem path to open. + /// @param[in] append If true, opens in `FileOpenMode::Append`; if false (default), truncates via `CreateAlways`. + /// @param[in] allowRead If true, grants `FileAccessMode::ReadWrite` on the handle; otherwise `Write`. + /// @param[in] shareMode Concurrent sharing permissions (defaults to `FileShareMode::Read`). + /// @return `Expected` containing the open writable `FileHandle`. + [[nodiscard]] static gp::Expected openWrite( + const gp::StringView path, + const bool append = false, + const bool allowRead = false, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + +public: + /// @section Metadata & Existence Queries + + /// @brief Queries metadata (`size`, `creationTime`, `lastWriteTime`, `lastAccessTime`, `attributes`) for `path`. + /// @param[in] path Physical UTF-8 filesystem path to inspect. + /// @return `Expected` containing the entry's `FileStats`, or `FileError::NotFound`. + [[nodiscard]] static gp::Expected getStats(const gp::StringView path) noexcept; + + /// @brief Checks whether a file or directory exists at `path`. + /// @param[in] path Physical UTF-8 filesystem path to check. + /// @return True if any filesystem entry exists at `path`, false otherwise. + [[nodiscard]] static bool exists(const gp::StringView path) noexcept; + + /// @brief Checks whether `path` exists and refers to a regular data file (not a directory). + /// @param[in] path Physical UTF-8 filesystem path to check. + /// @return True if `path` exists and is a regular file, false otherwise. + [[nodiscard]] static bool isFile(const gp::StringView path) noexcept; + + /// @brief Checks whether `path` exists and refers to a directory. + /// @param[in] path Physical UTF-8 filesystem path to check. + /// @return True if `path` exists and is a directory, false otherwise. + [[nodiscard]] static bool isDirectory(const gp::StringView path) noexcept; + + /// @brief Checks whether `path` exists and is marked read-only. + /// @param[in] path Physical UTF-8 filesystem path to check. + /// @return True if `path` exists and has `FileAttributeFlags::ReadOnly`, false otherwise. + [[nodiscard]] static bool isReadOnly(const gp::StringView path) noexcept; + + /// @brief Sets or clears the read-only attribute on `path`. + /// @param[in] path Physical UTF-8 filesystem path to modify. + /// @param[in] readOnly True to mark the entry read-only; false to make it writable. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected setReadOnly(const gp::StringView path, const bool readOnly) noexcept; + + /// @brief Queries the logical byte size of a regular file at `path`. + /// @param[in] path Physical UTF-8 file path to inspect. + /// @return `Expected` containing the file size in bytes, or `FileError::IsDirectory` / + /// `FileError::NotFound`. + [[nodiscard]] static gp::Expected fileSize(const gp::StringView path) noexcept; + +public: + /// @section Directory & File Mutations + + /// @brief Creates a single directory at `path` (succeeds idempotently if the directory already exists). + /// @param[in] path Physical UTF-8 directory path to create (parent directory must already exist). + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected createDirectory(const gp::StringView path) noexcept; + + /// @brief Recursively creates `path` and all missing parent directories (`mkdir -p` semantics) on the stack. + /// @param[in] path Physical UTF-8 directory tree path to create. + /// @return `Expected` containing `true` once the full directory chain exists, or a `FileError`. + static gp::Expected createDirectoryTree(const gp::StringView path) noexcept; + + /// @brief Deletes a regular file at `path`. + /// @param[in] path Physical UTF-8 file path to delete. + /// @return `Expected` containing `true` if deleted, or `FileError::NotFound` / `IsDirectory`. + static gp::Expected removeFile(const gp::StringView path) noexcept; + + /// @brief Deletes an empty directory at `path`. + /// @param[in] path Physical UTF-8 directory path to delete. + /// @return `Expected` containing `true` if removed, or `FileError::DirectoryNotEmpty` / + /// `NotFound`. + static gp::Expected removeDirectory(const gp::StringView path) noexcept; + + /// @brief Recursively deletes a directory and all contained files and subdirectories (`rm -rf` semantics). + /// @param[in] path Physical UTF-8 root directory path to delete. + /// @return `Expected` containing `true` on complete removal, or a `FileError`. + static gp::Expected removeDirectoryTree(const gp::StringView path) noexcept; + + /// @brief Renames or moves a file or directory from `sourcePath` to `destinationPath`. + /// @param[in] sourcePath Existing physical UTF-8 path. + /// @param[in] destinationPath Target physical UTF-8 path. + /// @param[in] overwrite If true (default), atomically replaces an existing file at `destinationPath`; if false, + /// fails with `FileError::AlreadyExists`. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + + /// @brief Copies a regular file from `sourcePath` to `destinationPath`. + /// @param[in] sourcePath Existing source file path. + /// @param[in] destinationPath Target destination file path. + /// @param[in] overwrite If true (default), overwrites any existing file at `destinationPath`; if false, fails with + /// `FileError::AlreadyExists`. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + +public: + /// @section Zero-Allocation Stack Directory Iteration + + /// @brief Iterates over the immediate children of `directoryPath` with zero heap allocations (ADR-0060). + /// @param[in] directoryPath Physical UTF-8 directory path to enumerate. + /// @param[in] visitor Stateless C callback invoked for each entry (`.` and `..` are automatically excluded). + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return `Expected` containing `true` on completion, or a `FileError`. + static gp::Expected iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @brief Iterates over the immediate children of `directoryPath` invoking any C++ callable/lambda + /// `(const DirectoryEntry&) -> DirectoryVisitControl` with zero heap allocations (ADR-0060). + /// @tparam InVisitor Callable matching `DirectoryVisitControl(const DirectoryEntry&)`. + /// @param[in] directoryPath Physical UTF-8 directory path to enumerate. + /// @param[in,out] visitor Callable invoked for each child entry. + /// @return `Expected` containing `true` on completion, or a `FileError`. + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectory(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryCallableImpl(directoryPath, visitor); + } + + /// @brief Recursively iterates over `directoryPath` and all nested subdirectories in depth-first pre-order. + /// @param[in] directoryPath Physical UTF-8 root directory path to enumerate. + /// @param[in] visitor Stateless C callback returning `Continue`, `SkipSubdirectory`, or `Stop`. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return `Expected` containing `true` on completion, or a `FileError`. + static gp::Expected iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @brief Recursively iterates over `directoryPath` invoking any C++ callable/lambda + /// `(const DirectoryEntry&) -> DirectoryVisitControl` with zero heap allocations (ADR-0060). + /// @tparam InVisitor Callable matching `DirectoryVisitControl(const DirectoryEntry&)`. + /// @param[in] directoryPath Physical UTF-8 root directory path to enumerate. + /// @param[in,out] visitor Callable invoked for each visited entry. + /// @return `Expected` containing `true` on completion, or a `FileError`. + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectoryRecursive(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryRecursiveCallableImpl(directoryPath, visitor); + } + +public: + /// @section Bulk & Crash-Safe Atomic File Utilities + + /// @brief Reads up to `bufferCapacity` bytes from `path` into a caller-provided raw memory buffer. + /// @param[in] path Physical UTF-8 file path to read. + /// @param[out] outBuffer Destination memory buffer. + /// @param[in] bufferCapacity Capacity of `outBuffer` in bytes. + /// @return `Expected` containing the number of bytes read into `outBuffer`. + [[nodiscard]] static gp::Expected + readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept; + + /// @brief Writes `sizeInBytes` from `data` to `path`, creating or truncating the file. + /// @param[in] path Physical UTF-8 file path to write. + /// @param[in] data Source memory buffer (may be `nullptr` only if `sizeInBytes == 0`). + /// @param[in] sizeInBytes Number of bytes to write. + /// @return `Expected` containing `true` if all bytes were written, or a `FileError`. + static gp::Expected + writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Writes a UTF-8 string view `text` to `path`, creating or truncating the file. + /// @param[in] path Physical UTF-8 file path to write. + /// @param[in] text UTF-8 text content to write. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected writeAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @brief Appends `sizeInBytes` from `data` to the end of `path` (creating the file if it does not exist). + /// @param[in] path Physical UTF-8 file path to append to. + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to append. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected + appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Appends a UTF-8 string view `text` to the end of `path` (creating the file if it does not exist). + /// @param[in] path Physical UTF-8 file path to append to. + /// @param[in] text UTF-8 text content to append. + /// @return `Expected` containing `true` on success, or a `FileError`. + static gp::Expected appendAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @brief Crash-safe atomic write transaction: writes to a temporary sibling file, flushes to disk, and atomically + /// renames over `path` (ADR-0060). + /// @details Guarantees that `path` is never left half-written or truncated to zero bytes if a crash or disk-full + /// error occurs mid-write. + /// @param[in] path Target physical UTF-8 file path to atomically create or replace. + /// @param[in] data Source memory buffer to write. + /// @param[in] sizeInBytes Number of bytes to write. + /// @return `Expected` containing `true` once committed and renamed, or a `FileError`. + static gp::Expected + writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Reads an entire binary file into any 1-byte element container (`gp::Vector`, `gp::String`). + /// @tparam InByteContainer Dynamic byte container type with `sizeof(ValueType) == 1`. + /// @param[in] path Physical UTF-8 file path to read. + /// @param[out] outBuffer Destination container resized once and populated with the file bytes. + /// @return `Expected` containing the number of bytes read into `outBuffer`. + template + requires(sizeof(typename InByteContainer::ValueType) == 1u) static gp::Expected + readAllBytes(const gp::StringView path, InByteContainer& outBuffer) noexcept + { + return readAllBytesImpl(path, outBuffer); + } + + /// @brief Reads an entire UTF-8 text file into any `gp::container::BasicString` (ADR-0060). + /// @tparam InAllocator Engine allocator satisfying `gp::concepts::IsAllocator`. + /// @param[in] path Physical UTF-8 file path to read. + /// @param[out] outString Destination string resized once via `resizeUninitialized` and populated with file bytes. + /// @return `Expected` containing the number of bytes read into `outString`. + template + static gp::Expected + readAllText(const gp::StringView path, gp::container::BasicString& outString) noexcept + { + return readAllTextImpl(path, outString); + } + + /// @brief Crash-safe atomic text write overload for `gp::StringView` payloads (ADR-0060). + /// @param[in] path Target physical UTF-8 file path to atomically create or replace. + /// @param[in] text UTF-8 text payload to commit atomically. + /// @return `Expected` containing `true` once committed and renamed, or a `FileError`. + static gp::Expected writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept; + +public: + /// @section Templated Composite & Allocator-Aware Helpers (Resolved on Derived `InSelf`) + + /// @brief Recursively creates `path` and all missing parent directories using `InSelf::createDirectory`. + /// @tparam InSelf Derived platform `FileSystem` class (`windows::FileSystem`, `unix::FileSystem`, etc.). + /// @param[in] path Physical UTF-8 directory tree path to create. + /// @return `Expected` containing `true` once the full directory chain exists, or a `FileError`. + template + static gp::Expected createDirectoryTreeImpl(const gp::StringView path) noexcept + { + if (path.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + if (InSelf::isDirectory(path)) + { + return true; + } + + PathBuffer normalized(path); + Paths::normalizeDirectoryName(normalized); + if (normalized.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + gp::StringView volume{}; + gp::StringView remainder{}; + const gp::StringView normView = normalized.view(); + Paths::splitVolumeSpecifier(normView, volume, remainder); + + gp::USize scanPos = volume.size(); + while (scanPos < normView.size() && Paths::isSeparator(normView[scanPos])) + { + ++scanPos; + } + + while (scanPos < normView.size()) + { + gp::USize nextSep = scanPos; + while (nextSep < normView.size() && !Paths::isSeparator(normView[nextSep])) + { + ++nextSep; + } + + const gp::StringView prefix = normView.substr(0u, nextSep); + if (!InSelf::isDirectory(prefix)) + { + const gp::Expected mkdirResult = InSelf::createDirectory(prefix); + if (!mkdirResult.hasValue() && mkdirResult.error() != FileError::AlreadyExists) + { + if (!InSelf::isDirectory(prefix)) + { + return mkdirResult; + } + } + } + + scanPos = nextSep; + while (scanPos < normView.size() && Paths::isSeparator(normView[scanPos])) + { + ++scanPos; + } + } + + return true; + } + + /// @brief Recursively deletes a directory and all contained files/subdirectories using `InSelf` primitives. + /// @tparam InSelf Derived platform `FileSystem` class. + /// @param[in] path Physical UTF-8 root directory path to delete. + /// @param[in] depth Current recursion depth (aborts with `MaxRecursionDepthExceeded` if `> 32`). + /// @return `Expected` containing `true` on complete removal, or a `FileError`. + template + static gp::Expected + removeDirectoryTreeImpl(const gp::StringView path, const gp::UInt32 depth = 0u) noexcept + { + if (path.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + if (depth > kMaxDirectoryRecursionDepth) + { + return gp::makeUnexpected(FileError::MaxRecursionDepthExceeded); + } + + const gp::Expected rootStats = InSelf::getStats(path); + if (!rootStats.hasValue()) + { + return gp::makeUnexpected(rootStats.error()); + } + if (!rootStats.value().isDirectory()) + { + return gp::makeUnexpected(FileError::NotDirectory); + } + + struct RemoveTreeContext + { + FileError firstError{ FileError::None }; + gp::UInt32 currentDepth{ 0u }; + }; + + RemoveTreeContext ctx{}; + ctx.currentDepth = depth; + + const DirectoryVisitorFn visitor = [](const DirectoryEntry& entry, void* const rawCtx) -> DirectoryVisitControl + { + RemoveTreeContext* const state = static_cast(rawCtx); + if (entry.isDirectory() && !entry.stats.isSymbolicLink()) + { + const gp::Expected subRes = + removeDirectoryTreeImpl(entry.path, state->currentDepth + 1u); + if (!subRes.hasValue()) + { + state->firstError = subRes.error(); + return DirectoryVisitControl::Stop; + } + } + else + { + if (entry.stats.isReadOnly()) + { + InSelf::setReadOnly(entry.path, false); + } + const gp::Expected rmRes = InSelf::removeFile(entry.path); + if (!rmRes.hasValue()) + { + state->firstError = rmRes.error(); + return DirectoryVisitControl::Stop; + } + } + return DirectoryVisitControl::Continue; + }; + + const gp::Expected iterRes = InSelf::iterateDirectory(path, visitor, &ctx); + if (!iterRes.hasValue()) + { + return iterRes; + } + if (ctx.firstError != FileError::None) + { + return gp::makeUnexpected(ctx.firstError); + } + + if (rootStats.value().isReadOnly()) + { + InSelf::setReadOnly(path, false); + } + return InSelf::removeDirectory(path); + } + + /// @brief Recursively traverses `directoryPath` in depth-first pre-order using `InSelf::iterateDirectory`. + /// @tparam InSelf Derived platform `FileSystem` class. + /// @param[in] directoryPath Physical UTF-8 root directory path to enumerate. + /// @param[in] visitor Stateless C callback returning `Continue`, `SkipSubdirectory`, or `Stop`. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @param[in] depth Current recursion depth (`0` at root). + /// @param[out] outStopped Set to true if `visitor` returned `DirectoryVisitControl::Stop`. + /// @return `Expected` containing `true` on completion, or a `FileError`. + template + static gp::Expected iterateDirectoryRecursiveImpl( + const gp::StringView directoryPath, + const DirectoryVisitorFn visitor, + void* const userData, + const gp::UInt32 depth, + bool& outStopped + ) noexcept + { + if (visitor == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + if (depth > kMaxDirectoryRecursionDepth) + { + return gp::makeUnexpected(FileError::MaxRecursionDepthExceeded); + } + + struct RecursiveWalkState + { + DirectoryVisitorFn userVisitor{ nullptr }; + void* userContext{ nullptr }; + gp::UInt32 currentDepth{ 0u }; + FileError childError{ FileError::None }; + bool stopped{ false }; + }; + + RecursiveWalkState state{}; + state.userVisitor = visitor; + state.userContext = userData; + state.currentDepth = depth; + + const DirectoryVisitorFn stepVisitor = [](const DirectoryEntry& rawEntry, + void* const rawState) -> DirectoryVisitControl + { + RecursiveWalkState* const walk = static_cast(rawState); + DirectoryEntry entryWithDepth = rawEntry; + entryWithDepth.depth = walk->currentDepth; + + const DirectoryVisitControl ctrl = walk->userVisitor(entryWithDepth, walk->userContext); + if (ctrl == DirectoryVisitControl::Stop) + { + walk->stopped = true; + return DirectoryVisitControl::Stop; + } + + if (entryWithDepth.isDirectory() && !entryWithDepth.stats.isSymbolicLink() && + ctrl != DirectoryVisitControl::SkipSubdirectory) + { + const gp::Expected childRes = iterateDirectoryRecursiveImpl( + entryWithDepth.path, walk->userVisitor, walk->userContext, walk->currentDepth + 1u, walk->stopped + ); + if (!childRes.hasValue()) + { + walk->childError = childRes.error(); + return DirectoryVisitControl::Stop; + } + if (walk->stopped) + { + return DirectoryVisitControl::Stop; + } + } + + return DirectoryVisitControl::Continue; + }; + + const gp::Expected iterRes = InSelf::iterateDirectory(directoryPath, stepVisitor, &state); + if (!iterRes.hasValue()) + { + return iterRes; + } + if (state.childError != FileError::None) + { + return gp::makeUnexpected(state.childError); + } + + outStopped = state.stopped; + return true; + } + + /// @brief Reads an entire binary file into any `gp::concepts::IsAllocator`-compatible byte/element container + /// exposing `clear()`, `resizeUninitialized(USize)` (or `resize(USize)`), and `data()` (ADR-0060). + /// @tparam InSelf Derived platform `FileSystem` class. + /// @tparam InByteContainer Dynamic byte container type (e.g., `gp::Vector` or `gp::String`). + /// @param[in] path Physical UTF-8 file path to read. + /// @param[out] outBuffer Destination byte container populated with the file payload. + /// @return `Expected` containing the number of bytes read into `outBuffer`. + template + requires(sizeof(typename InByteContainer::ValueType) == 1u) static gp::Expected + readAllBytesImpl(const gp::StringView path, InByteContainer& outBuffer) noexcept + { + outBuffer.clear(); + gp::Expected openRes = InSelf::openRead(path); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + FileHandle& handle = openRes.value(); + const gp::Expected sizeRes = handle.size(); + if (!sizeRes.hasValue()) + { + return gp::makeUnexpected(sizeRes.error()); + } + + const gp::USize byteCount = static_cast(sizeRes.value()); + if (byteCount == 0u) + { + return 0u; + } + + if constexpr (requires { outBuffer.resizeUninitialized(byteCount); }) + { + outBuffer.resizeUninitialized(byteCount); + } + else + { + outBuffer.resize(byteCount); + } + + const gp::Expected readRes = handle.read(outBuffer.data(), byteCount); + if (!readRes.hasValue()) + { + outBuffer.clear(); + return gp::makeUnexpected(readRes.error()); + } + + if (readRes.value() < byteCount) + { + outBuffer.resize(readRes.value()); + } + + return readRes.value(); + } + + /// @brief Reads an entire UTF-8 text file into any `gp::container::BasicString` (ADR-0060). + /// @tparam InSelf Derived platform `FileSystem` class. + /// @tparam InAllocator Engine allocator satisfying `gp::concepts::IsAllocator` (e.g., `DefaultAllocator`, + /// `ThreadScratchAllocator`, `LinearAllocator`). + /// @param[in] path Physical UTF-8 file path to read. + /// @param[out] outString Destination string resized once via `resizeUninitialized` and populated with file bytes. + /// @return `Expected` containing the number of bytes read into `outString`. + template + static gp::Expected + readAllTextImpl(const gp::StringView path, gp::container::BasicString& outString) noexcept + { + outString.clear(); + gp::Expected openRes = InSelf::openRead(path); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + FileHandle& handle = openRes.value(); + const gp::Expected sizeRes = handle.size(); + if (!sizeRes.hasValue()) + { + return gp::makeUnexpected(sizeRes.error()); + } + + const gp::USize byteCount = static_cast(sizeRes.value()); + if (byteCount == 0u) + { + return 0u; + } + + outString.resizeUninitialized(byteCount); + const gp::Expected readRes = handle.read(outString.data(), byteCount); + if (!readRes.hasValue()) + { + outString.clear(); + return gp::makeUnexpected(readRes.error()); + } + + if (readRes.value() < byteCount) + { + outString.resize(readRes.value()); + } + + return readRes.value(); + } + + /// @brief Bridges any C++ callable `(const DirectoryEntry&) -> DirectoryVisitControl` to `InSelf::iterateDirectory` + /// via a zero-allocation type-erased trampoline. + /// @tparam InSelf Derived platform `FileSystem` class. + /// @tparam InVisitor Callable type. + /// @param[in] directoryPath Physical UTF-8 directory path to enumerate. + /// @param[in,out] visitor Callable instance. + /// @return `Expected` from `InSelf::iterateDirectory`. + template + static gp::Expected + iterateDirectoryCallableImpl(const gp::StringView directoryPath, InVisitor& visitor) noexcept + { + const DirectoryVisitorFn trampoline = [](const DirectoryEntry& entry, + void* const rawCallable) -> DirectoryVisitControl + { + InVisitor* const fn = static_cast(rawCallable); + return (*fn)(entry); + }; + return InSelf::iterateDirectory( + directoryPath, trampoline, const_cast(static_cast(&visitor)) + ); + } + + /// @brief Bridges any C++ callable `(const DirectoryEntry&) -> DirectoryVisitControl` to + /// `InSelf::iterateDirectoryRecursive` via a zero-allocation trampoline. + /// @tparam InSelf Derived platform `FileSystem` class. + /// @tparam InVisitor Callable type. + /// @param[in] directoryPath Physical UTF-8 root directory path to enumerate. + /// @param[in,out] visitor Callable instance. + /// @return `Expected` from `InSelf::iterateDirectoryRecursive`. + template + static gp::Expected + iterateDirectoryRecursiveCallableImpl(const gp::StringView directoryPath, InVisitor& visitor) noexcept + { + const DirectoryVisitorFn trampoline = [](const DirectoryEntry& entry, + void* const rawCallable) -> DirectoryVisitControl + { + InVisitor* const fn = static_cast(rawCallable); + return (*fn)(entry); + }; + return InSelf::iterateDirectoryRecursive( + directoryPath, trampoline, const_cast(static_cast(&visitor)) + ); + } + + /// @brief Crash-safe atomic write transaction implemented on top of `InSelf` primitives (ADR-0060). + /// @details Uses a process-wide atomic sequence suffix (`.tmp.`) so concurrent `writeAtomic()` calls + /// targeting the same path from multiple threads never collide on a shared staging filename, flushes + /// all dirty kernel pages to non-volatile storage (`FlushFileBuffers` / `fsync`) before closing, and + /// atomically swaps the staging file over `path` (`MoveFileExW` / `rename`). + /// @tparam InSelf Derived platform `FileSystem` class. + /// @param[in] path Target physical UTF-8 file path to atomically create or replace. + /// @param[in] data Source memory buffer to write. + /// @param[in] sizeInBytes Number of bytes to write. + /// @return `Expected` containing `true` once committed and renamed, or a `FileError`. + template + static gp::Expected + writeAtomicImpl(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept + { + if (path.isEmpty()) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + if (sizeInBytes > 0u && data == nullptr) + { + return gp::makeUnexpected(FileError::InvalidArgument); + } + + static gp::thread::Atomic s_atomicWriteSeq(1ULL); + const gp::UInt64 seq = s_atomicWriteSeq.fetchAdd(1ULL, gp::memory::MemoryOrder::Relaxed); + + // Format ".tmp." on the stack with zero heap allocations and check PathBuffer capacity explicitly. + char suffixBuf[32]{}; + suffixBuf[0] = '.'; + suffixBuf[1] = 't'; + suffixBuf[2] = 'm'; + suffixBuf[3] = 'p'; + suffixBuf[4] = '.'; + char revDigits[24]{}; + gp::UInt64 tempSeq = seq; + gp::USize digitCount = 0u; + do + { + revDigits[digitCount++] = static_cast('0' + (tempSeq % 10ULL)); + tempSeq /= 10ULL; + } + while (tempSeq > 0ULL); + + gp::USize suffixLen = 5u; + for (gp::USize i = digitCount; i > 0u; --i) + { + suffixBuf[suffixLen++] = revDigits[i - 1u]; + } + + if ((path.size() + suffixLen) > kMaxPathLength) + { + return gp::makeUnexpected(FileError::InvalidPath); + } + + PathBuffer tempPath(path); + tempPath.append(gp::StringView(suffixBuf, suffixLen)); + + { + gp::Expected openRes = + InSelf::open(tempPath.view(), FileAccessMode::Write, FileOpenMode::CreateNew, FileShareMode::None); + if (!openRes.hasValue()) + { + return gp::makeUnexpected(openRes.error()); + } + + FileHandle& handle = openRes.value(); + if (sizeInBytes > 0u) + { + const gp::Expected writeRes = handle.write(data, sizeInBytes); + if (!writeRes.hasValue()) + { + handle.close(); + InSelf::removeFile(tempPath.view()); + return gp::makeUnexpected(writeRes.error()); + } + if (writeRes.value() != sizeInBytes) + { + handle.close(); + InSelf::removeFile(tempPath.view()); + return gp::makeUnexpected(FileError::DiskFull); + } + } + + const gp::Expected flushRes = handle.flush(); + if (!flushRes.hasValue()) + { + handle.close(); + InSelf::removeFile(tempPath.view()); + return gp::makeUnexpected(flushRes.error()); + } + + const gp::Expected closeRes = handle.close(); + if (!closeRes.hasValue()) + { + InSelf::removeFile(tempPath.view()); + return gp::makeUnexpected(closeRes.error()); + } + } + + const gp::Expected moveRes = InSelf::move(tempPath.view(), path, true); + if (!moveRes.hasValue()) + { + InSelf::removeFile(tempPath.view()); + return gp::makeUnexpected(moveRes.error()); + } + + return true; + } +}; + +} // namespace gp::platform::generic diff --git a/source/runtime/core/public/platforms/linux/system/LinuxFileSystem.hpp b/source/runtime/core/public/platforms/linux/system/LinuxFileSystem.hpp new file mode 100644 index 00000000..9ad2ede7 --- /dev/null +++ b/source/runtime/core/public/platforms/linux/system/LinuxFileSystem.hpp @@ -0,0 +1,20 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/unix/system/UnixFileSystem.hpp" + +namespace gp::platform::linux +{ + +/// @brief Linux implementation of Layer 0 OS file and directory utilities (ADR-0060). +class GP_CORE_API FileSystem : public gp::platform::unix::FileSystem +{ +public: + FileSystem() = delete; +}; + +} // namespace gp::platform::linux diff --git a/source/runtime/core/public/platforms/macos/system/MacOSFileSystem.hpp b/source/runtime/core/public/platforms/macos/system/MacOSFileSystem.hpp new file mode 100644 index 00000000..8e270241 --- /dev/null +++ b/source/runtime/core/public/platforms/macos/system/MacOSFileSystem.hpp @@ -0,0 +1,20 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/apple/system/AppleFileSystem.hpp" + +namespace gp::platform::macos +{ + +/// @brief macOS implementation of Layer 0 OS file and directory utilities (ADR-0060). +class GP_CORE_API FileSystem : public gp::platform::apple::FileSystem +{ +public: + FileSystem() = delete; +}; + +} // namespace gp::platform::macos diff --git a/source/runtime/core/public/platforms/unix/system/UnixFileSystem.hpp b/source/runtime/core/public/platforms/unix/system/UnixFileSystem.hpp new file mode 100644 index 00000000..b6432124 --- /dev/null +++ b/source/runtime/core/public/platforms/unix/system/UnixFileSystem.hpp @@ -0,0 +1,174 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/generic/system/GenericFileSystem.hpp" + +namespace gp::platform::unix +{ + +/// @brief POSIX implementation of Layer 0 OS file and directory utilities for Unix-derived platforms (ADR-0060). +/// @details Uses stack-allocated UTF-8 `PathBuffer` strings with `open`, `pread`/`pwrite`, `lseek`, `fstat`/`lstat`/ +/// `stat`, `chmod`, `mkdir`, `unlink`, `rmdir`, `rename`, `fsync`, and `opendir`/`readdir`. +class GP_CORE_API FileSystem : public gp::platform::generic::FileSystem +{ +public: + FileSystem() = delete; + +public: + /// @copydoc gp::platform::generic::FileSystem::open() + [[nodiscard]] static gp::Expected open( + const gp::StringView path, + const FileAccessMode access, + const FileOpenMode openMode, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::openRead() + [[nodiscard]] static gp::Expected + openRead(const gp::StringView path, const FileShareMode shareMode = FileShareMode::ReadWrite) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::openWrite() + [[nodiscard]] static gp::Expected openWrite( + const gp::StringView path, + const bool append = false, + const bool allowRead = false, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::getStats() + [[nodiscard]] static gp::Expected getStats(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::exists() + [[nodiscard]] static bool exists(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isFile() + [[nodiscard]] static bool isFile(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isDirectory() + [[nodiscard]] static bool isDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isReadOnly() + [[nodiscard]] static bool isReadOnly(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::setReadOnly() + static gp::Expected setReadOnly(const gp::StringView path, const bool readOnly) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::fileSize() + [[nodiscard]] static gp::Expected fileSize(const gp::StringView path) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::createDirectory() + static gp::Expected createDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::createDirectoryTree() + static gp::Expected createDirectoryTree(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeFile() + static gp::Expected removeFile(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeDirectory() + static gp::Expected removeDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeDirectoryTree() + static gp::Expected removeDirectoryTree(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::move() + static gp::Expected move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::copyFile() + static gp::Expected copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::iterateDirectory() + static gp::Expected iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectory(gp::StringView, InVisitor&&) + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectory(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryCallableImpl(directoryPath, visitor); + } + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectoryRecursive() + static gp::Expected iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectoryRecursive(gp::StringView, InVisitor&&) + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectoryRecursive(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryRecursiveCallableImpl(directoryPath, visitor); + } + +public: + /// @copydoc gp::platform::generic::FileSystem::readBytes() + [[nodiscard]] static gp::Expected + readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::readAllBytes() + template + requires(sizeof(typename InByteContainer::ValueType) == 1u) static gp::Expected + readAllBytes(const gp::StringView path, InByteContainer& outBuffer) noexcept + { + return readAllBytesImpl(path, outBuffer); + } + + /// @copydoc gp::platform::generic::FileSystem::readAllText() + template + static gp::Expected + readAllText(const gp::StringView path, gp::container::BasicString& outString) noexcept + { + return readAllTextImpl(path, outString); + } + + /// @copydoc gp::platform::generic::FileSystem::writeAllBytes() + static gp::Expected + writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAllText() + static gp::Expected writeAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::appendAllBytes() + static gp::Expected + appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::appendAllText() + static gp::Expected appendAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAtomic() + static gp::Expected + writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAtomicText() + static gp::Expected writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept; +}; + +} // namespace gp::platform::unix diff --git a/source/runtime/core/public/platforms/windows/system/WindowsFileSystem.hpp b/source/runtime/core/public/platforms/windows/system/WindowsFileSystem.hpp new file mode 100644 index 00000000..f3bf242e --- /dev/null +++ b/source/runtime/core/public/platforms/windows/system/WindowsFileSystem.hpp @@ -0,0 +1,179 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/generic/system/GenericFileSystem.hpp" + +namespace gp::platform::windows +{ + +/// @brief Win32 implementation of Layer 0 OS file and directory utilities (ADR-0060). +/// @details Uses wide UTF-16 stack buffers (`wchar_t[kMaxPathLength + 1]`) with `CreateFileW`, `OVERLAPPED` positional +/// `ReadFile`/`WriteFile`, `GetFileAttributesExW`, `SetFileAttributesW`, `CreateDirectoryW`, `DeleteFileW`, +/// `RemoveDirectoryW`, `MoveFileExW` (`MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH`), `CopyFileExW`, +/// and zero-syscall-overhead `FindFirstFileExW` (`FindExInfoBasic`, `FIND_FIRST_EX_LARGE_FETCH`). +class GP_CORE_API FileSystem : public gp::platform::generic::FileSystem +{ +public: + FileSystem() = delete; + +public: + /// @copydoc gp::platform::generic::FileSystem::open() + /// @note Invokes Win32 `CreateFileW` after converting the UTF-8 path into a stack-allocated UTF-16 buffer. + [[nodiscard]] static gp::Expected open( + const gp::StringView path, + const FileAccessMode access, + const FileOpenMode openMode, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::openRead() + [[nodiscard]] static gp::Expected + openRead(const gp::StringView path, const FileShareMode shareMode = FileShareMode::ReadWrite) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::openWrite() + [[nodiscard]] static gp::Expected openWrite( + const gp::StringView path, + const bool append = false, + const bool allowRead = false, + const FileShareMode shareMode = FileShareMode::Read + ) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::getStats() + /// @note Queries `GetFileAttributesExW(GetFileExInfoStandard)` and normalizes `FILETIME` ticks to Unix Epoch ns. + [[nodiscard]] static gp::Expected getStats(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::exists() + [[nodiscard]] static bool exists(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isFile() + [[nodiscard]] static bool isFile(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isDirectory() + [[nodiscard]] static bool isDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::isReadOnly() + [[nodiscard]] static bool isReadOnly(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::setReadOnly() + static gp::Expected setReadOnly(const gp::StringView path, const bool readOnly) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::fileSize() + [[nodiscard]] static gp::Expected fileSize(const gp::StringView path) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::createDirectory() + static gp::Expected createDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::createDirectoryTree() + static gp::Expected createDirectoryTree(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeFile() + static gp::Expected removeFile(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeDirectory() + static gp::Expected removeDirectory(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::removeDirectoryTree() + static gp::Expected removeDirectoryTree(const gp::StringView path) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::move() + static gp::Expected move( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::copyFile() + static gp::Expected copyFile( + const gp::StringView sourcePath, const gp::StringView destinationPath, const bool overwrite = true + ) noexcept; + +public: + /// @copydoc gp::platform::generic::FileSystem::iterateDirectory() + /// @note Populates `DirectoryEntry::stats` directly from `WIN32_FIND_DATAW` with zero extra syscalls per entry. + static gp::Expected iterateDirectory( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectory(gp::StringView, InVisitor&&) + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectory(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryCallableImpl(directoryPath, visitor); + } + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectoryRecursive() + static gp::Expected iterateDirectoryRecursive( + const gp::StringView directoryPath, const DirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::iterateDirectoryRecursive(gp::StringView, InVisitor&&) + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const DirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectoryRecursive(const gp::StringView directoryPath, InVisitor&& visitor) noexcept + { + return iterateDirectoryRecursiveCallableImpl(directoryPath, visitor); + } + +public: + /// @copydoc gp::platform::generic::FileSystem::readBytes() + [[nodiscard]] static gp::Expected + readBytes(const gp::StringView path, void* const outBuffer, const gp::USize bufferCapacity) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::readAllBytes() + template + requires(sizeof(typename InByteContainer::ValueType) == 1u) static gp::Expected + readAllBytes(const gp::StringView path, InByteContainer& outBuffer) noexcept + { + return readAllBytesImpl(path, outBuffer); + } + + /// @copydoc gp::platform::generic::FileSystem::readAllText() + template + static gp::Expected + readAllText(const gp::StringView path, gp::container::BasicString& outString) noexcept + { + return readAllTextImpl(path, outString); + } + + /// @copydoc gp::platform::generic::FileSystem::writeAllBytes() + static gp::Expected + writeAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAllText() + static gp::Expected writeAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::appendAllBytes() + static gp::Expected + appendAllBytes(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::appendAllText() + static gp::Expected appendAllText(const gp::StringView path, const gp::StringView text) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAtomic() + static gp::Expected + writeAtomic(const gp::StringView path, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @copydoc gp::platform::generic::FileSystem::writeAtomicText() + static gp::Expected writeAtomicText(const gp::StringView path, const gp::StringView text) noexcept; +}; + +} // namespace gp::platform::windows diff --git a/source/runtime/core/public/vfs/IMountBackend.hpp b/source/runtime/core/public/vfs/IMountBackend.hpp new file mode 100644 index 00000000..f5cc1fd3 --- /dev/null +++ b/source/runtime/core/public/vfs/IMountBackend.hpp @@ -0,0 +1,161 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileHandle.hpp" +#include "platforms/base/system/FileTypes.hpp" +#include "platforms/base/system/PathTypes.hpp" +#include "templates/Expected.hpp" +#include "vfs/VfsEnums.hpp" +#include "vfs/VfsTypes.hpp" // IWYU pragma: keep + +namespace gp::vfs +{ + +/// @brief Abstract storage medium contract for a mounted VFS layer (`PhysicalMountBackend`, `MemoryMountBackend`, +/// or future `PakMountBackend`) (ADR-0007, ADR-0044, ADR-0060). +/// @details All `relativePath` parameters passed into `IMountBackend` are guaranteed by `VirtualFileSystem` to be +/// pre-normalized (`'/'` separators, no leading slash) and sandbox-validated (`collapseRelativeDirectories` +/// already verified zero leading `".."` escape segments). +class GP_CORE_API IMountBackend +{ +public: + /// @brief Default constructor. + constexpr IMountBackend() noexcept = default; + + /// @brief Virtual destructor. + virtual ~IMountBackend() noexcept = default; + + IMountBackend(const IMountBackend&) = delete; + IMountBackend& operator=(const IMountBackend&) = delete; + IMountBackend(IMountBackend&&) = delete; + IMountBackend& operator=(IMountBackend&&) = delete; + +public: + /// @brief Returns the physical OS root directory or diagnostic identifier of this backend. + /// @return Non-owning `gp::StringView` describing the mount root. + [[nodiscard]] virtual gp::StringView rootPath() const noexcept = 0; + + /// @brief Checks whether this backend is backed by a physical OS directory capable of resolving native OS paths. + /// @return True if `resolvePhysicalPath()` is supported, false for in-memory or compressed archive backends. + [[nodiscard]] virtual bool isPhysical() const noexcept = 0; + + /// @brief Resolves a sandbox-validated `relativePath` to a physical OS `PathBuffer` if supported by this backend. + /// @param[in] relativePath Sandbox-validated relative path within the mount. + /// @return `Expected` containing the physical OS path, or `VfsError::NotSupported`. + [[nodiscard]] virtual gp::Expected + resolvePhysicalPath(const gp::StringView relativePath) const noexcept = 0; + + /// @brief Checks whether a file or directory exists at `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative path within the mount (empty view denotes the mount root). + /// @return True if the entry exists in this backend, false otherwise. + [[nodiscard]] virtual bool exists(const gp::StringView relativePath) const noexcept = 0; + + /// @brief Queries metadata (`size`, timestamps, `FileAttributeFlags`) for `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative path within the mount. + /// @return `Expected` containing the entry's metadata, or `VfsError::NotFound`. + [[nodiscard]] virtual gp::Expected + getStats(const gp::StringView relativePath) const noexcept = 0; + + /// @brief Opens a native OS `FileHandle` for `relativePath` when supported by the backend. + /// @param[in] relativePath Sandbox-validated relative path within the mount. + /// @param[in] access Read/Write access flags. + /// @param[in] openMode Creation/truncation disposition. + /// @param[in] shareMode Concurrent sharing permissions. + /// @return `Expected` containing the open OS handle, or `VfsError::NotSupported`. + [[nodiscard]] virtual gp::Expected openFileHandle( + const gp::StringView relativePath, + const gp::platform::FileAccessMode access, + const gp::platform::FileOpenMode openMode, + const gp::platform::FileShareMode shareMode + ) noexcept = 0; + + /// @brief Reads up to `bytesToRead` bytes starting at `offset` from `relativePath` into `outBuffer`. + /// @note Works uniformly across both physical OS mounts and non-physical (`MemoryMountBackend` / `.pak`) mounts. + /// @param[in] relativePath Sandbox-validated relative file path. + /// @param[in] offset Byte offset from the start of the file. + /// @param[out] outBuffer Destination memory buffer. + /// @param[in] bytesToRead Maximum number of bytes to read. + /// @return `Expected` containing the number of bytes read, or a `VfsError`. + [[nodiscard]] virtual gp::Expected readBytesAt( + const gp::StringView relativePath, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead + ) const noexcept = 0; + + /// @brief Creates or overwrites `relativePath` with `sizeInBytes` from `data`. + /// @param[in] relativePath Sandbox-validated relative file path. + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to write. + /// @param[in] append If true, appends to the end of the file; if false, truncates and overwrites. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected writeBytes( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes, const bool append + ) noexcept = 0; + + /// @brief Atomically writes `sizeInBytes` from `data` to `relativePath` via temporary staging and rename. + /// @param[in] relativePath Sandbox-validated relative file path. + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to write. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected writeAtomic( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes + ) noexcept = 0; + + /// @brief Creates a single directory at `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative directory path. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected createDirectory(const gp::StringView relativePath) noexcept = 0; + + /// @brief Recursively creates `relativePath` and all missing parent directories inside this backend. + /// @param[in] relativePath Sandbox-validated relative directory tree path. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected createDirectoryTree(const gp::StringView relativePath) noexcept = 0; + + /// @brief Removes a regular file at `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative file path. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected removeFile(const gp::StringView relativePath) noexcept = 0; + + /// @brief Removes an empty directory at `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative directory path. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected removeDirectory(const gp::StringView relativePath) noexcept = 0; + + /// @brief Recursively removes a directory and all its contents at `relativePath` inside this backend. + /// @param[in] relativePath Sandbox-validated relative directory path. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected removeDirectoryTree(const gp::StringView relativePath) noexcept = 0; + + /// @brief Renames or moves an entry from `sourceRelativePath` to `destinationRelativePath` within this backend. + /// @param[in] sourceRelativePath Existing sandbox-validated relative path. + /// @param[in] destinationRelativePath Target sandbox-validated relative path. + /// @param[in] overwrite If true, replaces any existing target entry. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected move( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept = 0; + + /// @brief Copies a regular file from `sourceRelativePath` to `destinationRelativePath` within this backend. + /// @param[in] sourceRelativePath Existing sandbox-validated relative file path. + /// @param[in] destinationRelativePath Target sandbox-validated relative file path. + /// @param[in] overwrite If true, replaces any existing target file. + /// @return `Expected` containing `true` on success, or a `VfsError`. + virtual gp::Expected copyFile( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept = 0; + + /// @brief Iterates over the immediate children of `relativeDirectoryPath` inside this backend. + /// @param[in] relativeDirectoryPath Sandbox-validated relative directory path (empty view for mount root). + /// @param[in] visitor Stateless Layer 0 `DirectoryVisitorFn` receiving each child's leaf name and `FileStats`. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return `Expected` containing `true` on completion, or a `VfsError`. + virtual gp::Expected iterateDirectory( + const gp::StringView relativeDirectoryPath, const gp::platform::DirectoryVisitorFn visitor, void* const userData + ) const noexcept = 0; +}; + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/MemoryMountBackend.hpp b/source/runtime/core/public/vfs/MemoryMountBackend.hpp new file mode 100644 index 00000000..3baf5700 --- /dev/null +++ b/source/runtime/core/public/vfs/MemoryMountBackend.hpp @@ -0,0 +1,149 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/strings/String.hpp" // IWYU pragma: keep +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/system/PathTypes.hpp" +#include "threading/sync/SharedMutex.hpp" +#include "vfs/IMountBackend.hpp" + +namespace gp::vfs +{ + +/// @brief Maximum number of virtual files and directories stored inside a `MemoryMountBackend` instance. +inline constexpr gp::USize kMaxMemoryMountNodes = 128u; + +/// @brief In-memory virtual filesystem backend for unit testing, embedded engine shaders/fonts, and scratch mounts +/// (ADR-0044, ADR-0060). +/// @details Stores virtual directory and file nodes inside an internal table guarded by a `gp::thread::SharedMutex`, +/// allowing full VFS read/write/atomic-write/mkdir/remove/move/copy/iterate workflows without touching the +/// physical OS disk. +class GP_CORE_API MemoryMountBackend final : public IMountBackend +{ +public: + /// @brief Default-constructs an empty `MemoryMountBackend` with an active root directory node. + [[nodiscard]] MemoryMountBackend() noexcept; + + /// @brief Constructs an empty `MemoryMountBackend` labeled with `identifier`. + /// @param[in] identifier Diagnostic identifier returned by `rootPath()` (e.g., `"[memory:test]"`). + [[nodiscard]] explicit MemoryMountBackend(const gp::StringView identifier) noexcept; + + /// @brief Virtual destructor. + virtual ~MemoryMountBackend() noexcept override = default; + + /// @brief Removes all files and directories from this in-memory backend, resetting it to an empty root. + void clear() noexcept; + +public: + /// @copydoc IMountBackend::rootPath() + [[nodiscard]] virtual gp::StringView rootPath() const noexcept override; + + /// @copydoc IMountBackend::isPhysical() + [[nodiscard]] virtual bool isPhysical() const noexcept override; + + /// @copydoc IMountBackend::resolvePhysicalPath() + [[nodiscard]] virtual gp::Expected + resolvePhysicalPath(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::exists() + [[nodiscard]] virtual bool exists(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::getStats() + [[nodiscard]] virtual gp::Expected + getStats(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::openFileHandle() + [[nodiscard]] virtual gp::Expected openFileHandle( + const gp::StringView relativePath, + const gp::platform::FileAccessMode access, + const gp::platform::FileOpenMode openMode, + const gp::platform::FileShareMode shareMode + ) noexcept override; + + /// @copydoc IMountBackend::readBytesAt() + [[nodiscard]] virtual gp::Expected readBytesAt( + const gp::StringView relativePath, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead + ) const noexcept override; + + /// @copydoc IMountBackend::writeBytes() + virtual gp::Expected writeBytes( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes, const bool append + ) noexcept override; + + /// @copydoc IMountBackend::writeAtomic() + virtual gp::Expected writeAtomic( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes + ) noexcept override; + + /// @copydoc IMountBackend::createDirectory() + virtual gp::Expected createDirectory(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::createDirectoryTree() + virtual gp::Expected createDirectoryTree(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeFile() + virtual gp::Expected removeFile(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeDirectory() + virtual gp::Expected removeDirectory(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeDirectoryTree() + virtual gp::Expected removeDirectoryTree(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::move() + virtual gp::Expected move( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept override; + + /// @copydoc IMountBackend::copyFile() + virtual gp::Expected copyFile( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept override; + + /// @copydoc IMountBackend::iterateDirectory() + virtual gp::Expected iterateDirectory( + const gp::StringView relativeDirectoryPath, const gp::platform::DirectoryVisitorFn visitor, void* const userData + ) const noexcept override; + +private: + struct MemoryNode + { + gp::PathBuffer relativePath{}; + gp::String content{}; + gp::platform::FileStats stats{}; + bool active{ false }; + }; + +private: + /// @brief Normalizes and validates a relative path inside the in-memory tree. + /// @param[in] rawRelativePath Input relative path view. + /// @param[out] outNormalized Receives the normalized relative path without leading/trailing slashes. + /// @return `VfsError::None` on success, or `VfsError::SandboxEscapeViolation`. + [[nodiscard]] static VfsError + normalizeRelativeKey(const gp::StringView rawRelativePath, gp::PathBuffer& outNormalized) noexcept; + + /// @brief Locates an active node matching `normalizedKey` (caller must hold `m_mutex`). + /// @param[in] normalizedKey Normalized relative path key. + /// @return Index in `m_nodes`, or `kMaxMemoryMountNodes` if not found. + [[nodiscard]] gp::USize findNodeIndexUnlocked(const gp::StringView normalizedKey) const noexcept; + + /// @brief Allocates an unused slot in `m_nodes` (caller must hold exclusive `m_mutex`). + /// @return Index in `m_nodes`, or `kMaxMemoryMountNodes` if full. + [[nodiscard]] gp::USize allocateNodeSlotUnlocked() noexcept; + + /// @brief Creates a single directory node (caller must hold exclusive `m_mutex`). + /// @param[in] normalizedKey Normalized relative directory path key. + /// @return `Expected`. + gp::Expected createDirectoryUnlocked(const gp::StringView normalizedKey) noexcept; + +private: + mutable gp::thread::SharedMutex m_mutex{}; + gp::PathBuffer m_identifier{ "[memory]" }; + MemoryNode m_nodes[kMaxMemoryMountNodes]{}; +}; + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/PhysicalMountBackend.hpp b/source/runtime/core/public/vfs/PhysicalMountBackend.hpp new file mode 100644 index 00000000..67c8740b --- /dev/null +++ b/source/runtime/core/public/vfs/PhysicalMountBackend.hpp @@ -0,0 +1,112 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/system/PathTypes.hpp" +#include "vfs/IMountBackend.hpp" + +namespace gp::vfs +{ + +/// @brief Physical operating system directory mount backend for `gp::vfs::VirtualFileSystem` (ADR-0044, ADR-0060). +/// @details Routes VFS operations to Layer 0 `gp::platform::FileSystem` rooted at a normalized OS directory +/// (`m_rootPath`, guaranteed trailing `'/'`), mechanically enforcing a second sandbox-escape check via +/// `gp::platform::Paths::collapseRelativeDirectories()` and `Paths::isUnderDirectory()`. +class GP_CORE_API PhysicalMountBackend final : public IMountBackend +{ +public: + /// @brief Default constructor (uninitialized empty root). + [[nodiscard]] constexpr PhysicalMountBackend() noexcept = default; + + /// @brief Constructs a `PhysicalMountBackend` rooted at `physicalRootDir`. + /// @param[in] physicalRootDir Physical OS directory path (normalized automatically with a trailing `'/'`). + [[nodiscard]] explicit PhysicalMountBackend(const gp::StringView physicalRootDir) noexcept; + + /// @brief Virtual destructor. + virtual ~PhysicalMountBackend() noexcept override = default; + + /// @brief Initializes or re-binds the physical OS directory root of this backend. + /// @param[in] physicalRootDir Physical OS directory path. + /// @return True if `physicalRootDir` is non-empty and valid, false otherwise. + bool setRootPath(const gp::StringView physicalRootDir) noexcept; + +public: + /// @copydoc IMountBackend::rootPath() + [[nodiscard]] virtual gp::StringView rootPath() const noexcept override; + + /// @copydoc IMountBackend::isPhysical() + [[nodiscard]] virtual bool isPhysical() const noexcept override; + + /// @copydoc IMountBackend::resolvePhysicalPath() + [[nodiscard]] virtual gp::Expected + resolvePhysicalPath(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::exists() + [[nodiscard]] virtual bool exists(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::getStats() + [[nodiscard]] virtual gp::Expected + getStats(const gp::StringView relativePath) const noexcept override; + + /// @copydoc IMountBackend::openFileHandle() + [[nodiscard]] virtual gp::Expected openFileHandle( + const gp::StringView relativePath, + const gp::platform::FileAccessMode access, + const gp::platform::FileOpenMode openMode, + const gp::platform::FileShareMode shareMode + ) noexcept override; + + /// @copydoc IMountBackend::readBytesAt() + [[nodiscard]] virtual gp::Expected readBytesAt( + const gp::StringView relativePath, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead + ) const noexcept override; + + /// @copydoc IMountBackend::writeBytes() + virtual gp::Expected writeBytes( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes, const bool append + ) noexcept override; + + /// @copydoc IMountBackend::writeAtomic() + virtual gp::Expected writeAtomic( + const gp::StringView relativePath, const void* const data, const gp::USize sizeInBytes + ) noexcept override; + + /// @copydoc IMountBackend::createDirectory() + virtual gp::Expected createDirectory(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::createDirectoryTree() + virtual gp::Expected createDirectoryTree(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeFile() + virtual gp::Expected removeFile(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeDirectory() + virtual gp::Expected removeDirectory(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::removeDirectoryTree() + virtual gp::Expected removeDirectoryTree(const gp::StringView relativePath) noexcept override; + + /// @copydoc IMountBackend::move() + virtual gp::Expected move( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept override; + + /// @copydoc IMountBackend::copyFile() + virtual gp::Expected copyFile( + const gp::StringView sourceRelativePath, const gp::StringView destinationRelativePath, const bool overwrite + ) noexcept override; + + /// @copydoc IMountBackend::iterateDirectory() + virtual gp::Expected iterateDirectory( + const gp::StringView relativeDirectoryPath, const gp::platform::DirectoryVisitorFn visitor, void* const userData + ) const noexcept override; + +private: + gp::PathBuffer m_rootPath{}; +}; + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/VfsEnums.hpp b/source/runtime/core/public/vfs/VfsEnums.hpp new file mode 100644 index 00000000..4c3e1717 --- /dev/null +++ b/source/runtime/core/public/vfs/VfsEnums.hpp @@ -0,0 +1,237 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" + +namespace gp::vfs +{ + +/// @brief Explicit diagnostic error codes returned by Layer 1 `gp::vfs::VirtualFileSystem` and `IMountBackend` +/// (ADR-0044, ADR-0060). +enum class VfsError : gp::UInt8 +{ + /// @brief Operation completed without error. + None = 0, + + /// @brief The requested virtual file or directory does not exist in any mounted backend for the URI scheme. + NotFound = 1, + + /// @brief The target virtual file or directory already exists when exclusive creation was requested. + AlreadyExists = 2, + + /// @brief The operating system or VFS backend denied access (e.g., read-only physical file). + AccessDenied = 3, + + /// @brief The URI lacks a valid `"scheme://"` prefix or has an empty/malformed relative sub-path. + InvalidUri = 4, + + /// @brief No mount point is currently registered for the requested URI scheme (e.g., `"unknown://"`). + SchemeNotMounted = 5, + + /// @brief Relative `".."` segments in the URI attempted to climb above the mount root (ADR-0044 Invariant 1). + SandboxEscapeViolation = 6, + + /// @brief Attempted a write, directory creation, or deletion on a `MountAccess::ReadOnly` scheme (`engine://`, + /// `game://`). + ReadOnlyMount = 7, + + /// @brief A directory was encountered where a regular file was expected. + IsDirectory = 8, + + /// @brief A regular file was encountered where a directory was expected. + NotDirectory = 9, + + /// @brief Attempted to remove a non-empty directory without recursive deletion. + DirectoryNotEmpty = 10, + + /// @brief The mount table or in-memory backend capacity limit was reached. + MountTableFull = 11, + + /// @brief An invalid argument (null pointer or invalid flags) was provided. + InvalidArgument = 12, + + /// @brief The underlying storage medium is full. + DiskFull = 13, + + /// @brief Directory recursion depth exceeded `kMaxDirectoryRecursionDepth` (`32`). + MaxRecursionDepthExceeded = 14, + + /// @brief Attempted to move/rename a file across two different mount backends or schemes. + CrossMountOperation = 15, + + /// @brief The operation is not supported by the target `IMountBackend` (e.g., raw OS `FileHandle` on a memory/pak + /// backend). + NotSupported = 16, + + /// @brief Underlying Layer 0 OS I/O failure. + IoFailure = 17 +}; + +/// @brief Priority tier governing read overlay order when multiple mounts share one logical URI scheme (ADR-0044). +/// @details Higher numerical priority mounts are queried first during read and existence resolution +/// (`DeveloperOverride` +/// > `ModOverride` > `Patch` > `DLC` > `Base`). +enum class MountPriority : gp::UInt16 +{ + /// @brief Shipped base engine or game archive/folder (`100`). + Base = 100u, + + /// @brief Expansion pack or downloadable content mount (`200`). + DLC = 200u, + + /// @brief Official title update or hotfix patch archive (`300`). + Patch = 300u, + + /// @brief Community or user modification overlay (`400`). + ModOverride = 400u, + + /// @brief Local developer loose-file override or live hot-reload folder (`500`). + DeveloperOverride = 500u +}; + +/// @brief Access permission contract enforced on a VFS mount point (ADR-0044). +enum class MountAccess : gp::UInt8 +{ + /// @brief Immutable mount point (`engine://`, `game://`, `.pak` archives): all mutation calls return + /// `VfsError::ReadOnlyMount`. + ReadOnly = 0, + + /// @brief Writable mount point (`user://`, `appdata://`, `cache://`, `temp://`). + ReadWrite = 1 +}; + +/// @brief Translates a Layer 0 `gp::platform::FileError` into the corresponding Layer 1 `gp::vfs::VfsError`. +/// @param[in] fileError Layer 0 OS filesystem error code. +/// @return Equivalent Layer 1 `VfsError`. +[[nodiscard]] constexpr VfsError mapFileErrorToVfsError(const gp::platform::FileError fileError) noexcept +{ + switch (fileError) + { + case gp::platform::FileError::None: + return VfsError::None; + case gp::platform::FileError::NotFound: + return VfsError::NotFound; + case gp::platform::FileError::AlreadyExists: + return VfsError::AlreadyExists; + case gp::platform::FileError::AccessDenied: + case gp::platform::FileError::SharingViolation: + return VfsError::AccessDenied; + case gp::platform::FileError::ReadOnlyFileSystem: + return VfsError::ReadOnlyMount; + case gp::platform::FileError::InvalidPath: + return VfsError::InvalidUri; + case gp::platform::FileError::InvalidArgument: + case gp::platform::FileError::InvalidHandle: + return VfsError::InvalidArgument; + case gp::platform::FileError::IsDirectory: + return VfsError::IsDirectory; + case gp::platform::FileError::NotDirectory: + return VfsError::NotDirectory; + case gp::platform::FileError::DirectoryNotEmpty: + return VfsError::DirectoryNotEmpty; + case gp::platform::FileError::DiskFull: + return VfsError::DiskFull; + case gp::platform::FileError::MaxRecursionDepthExceeded: + return VfsError::MaxRecursionDepthExceeded; + case gp::platform::FileError::CrossDeviceLink: + return VfsError::CrossMountOperation; + case gp::platform::FileError::NotSupported: + return VfsError::NotSupported; + case gp::platform::FileError::TooManyOpenFiles: + case gp::platform::FileError::IoFailure: + default: + return VfsError::IoFailure; + } +} + +/// @brief Returns a human-readable ASCII name for a `VfsError` enum value (for diagnostics and logging). +/// @param[in] error The `VfsError` value to stringify. +/// @return Null-terminated static string view naming the VFS error code. +[[nodiscard]] constexpr gp::StringView toString(const VfsError error) noexcept +{ + switch (error) + { + case VfsError::None: + return "None"; + case VfsError::NotFound: + return "NotFound"; + case VfsError::AlreadyExists: + return "AlreadyExists"; + case VfsError::AccessDenied: + return "AccessDenied"; + case VfsError::InvalidUri: + return "InvalidUri"; + case VfsError::SchemeNotMounted: + return "SchemeNotMounted"; + case VfsError::SandboxEscapeViolation: + return "SandboxEscapeViolation"; + case VfsError::ReadOnlyMount: + return "ReadOnlyMount"; + case VfsError::IsDirectory: + return "IsDirectory"; + case VfsError::NotDirectory: + return "NotDirectory"; + case VfsError::DirectoryNotEmpty: + return "DirectoryNotEmpty"; + case VfsError::MountTableFull: + return "MountTableFull"; + case VfsError::InvalidArgument: + return "InvalidArgument"; + case VfsError::DiskFull: + return "DiskFull"; + case VfsError::MaxRecursionDepthExceeded: + return "MaxRecursionDepthExceeded"; + case VfsError::CrossMountOperation: + return "CrossMountOperation"; + case VfsError::NotSupported: + return "NotSupported"; + case VfsError::IoFailure: + return "IoFailure"; + default: + return "Unknown"; + } +} + +/// @brief Returns a human-readable ASCII name for a `MountPriority` tier (for diagnostics and console output). +/// @param[in] priority The `MountPriority` tier to stringify. +/// @return Null-terminated static string view naming the priority tier. +[[nodiscard]] constexpr gp::StringView toString(const MountPriority priority) noexcept +{ + switch (priority) + { + case MountPriority::Base: + return "Base"; + case MountPriority::DLC: + return "DLC"; + case MountPriority::Patch: + return "Patch"; + case MountPriority::ModOverride: + return "ModOverride"; + case MountPriority::DeveloperOverride: + return "DeveloperOverride"; + default: + return "Custom"; + } +} + +/// @brief Returns a human-readable ASCII name for a `MountAccess` policy (for diagnostics and console output). +/// @param[in] access The `MountAccess` policy to stringify. +/// @return Null-terminated static string view (`"ReadOnly"` or `"ReadWrite"`). +[[nodiscard]] constexpr gp::StringView toString(const MountAccess access) noexcept +{ + switch (access) + { + case MountAccess::ReadOnly: + return "ReadOnly"; + case MountAccess::ReadWrite: + return "ReadWrite"; + default: + return "Unknown"; + } +} + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/VfsForward.hpp b/source/runtime/core/public/vfs/VfsForward.hpp new file mode 100644 index 00000000..c8a29cd7 --- /dev/null +++ b/source/runtime/core/public/vfs/VfsForward.hpp @@ -0,0 +1,25 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "CoreMinimal.hpp" + +namespace gp::vfs +{ + +enum class VfsError : gp::UInt8; +enum class MountPriority : gp::UInt16; +enum class MountAccess : gp::UInt8; + +struct ParsedUri; +struct MountPointDesc; +struct VfsDirectoryEntry; + +class IMountBackend; +class PhysicalMountBackend; +class MemoryMountBackend; +class VirtualFileSystem; + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/VfsTypes.hpp b/source/runtime/core/public/vfs/VfsTypes.hpp new file mode 100644 index 00000000..68252f82 --- /dev/null +++ b/source/runtime/core/public/vfs/VfsTypes.hpp @@ -0,0 +1,123 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/strings/FixedString.hpp" +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileTypes.hpp" +#include "platforms/base/system/PathTypes.hpp" +#include "vfs/VfsEnums.hpp" + +namespace gp::vfs +{ + +/// @brief Maximum UTF-8 byte length for a normalized VFS scheme prefix including `"://"` (e.g., `"appdata://"`). +inline constexpr gp::USize kMaxSchemeLength = 32u; + +/// @brief Maximum number of concurrent mount points registered in `VirtualFileSystem` (zero-allocation `.bss` table). +inline constexpr gp::USize kMaxMountPoints = 32u; + +/// @brief Number of open-addressed hash slots (`512` slots = `4 KiB` on stack) used for O(1) shadowed-entry +/// deduplication during multi-mount VFS directory iteration (ADR-0044, ADR-0060). +inline constexpr gp::USize kVfsMergedDirectoryHashSlots = 512u; + +/// @brief Canonical logical URI schemes defined by ADR-0044. +inline constexpr gp::StringView kEngineScheme = "engine://"; +inline constexpr gp::StringView kGameScheme = "game://"; +inline constexpr gp::StringView kUserScheme = "user://"; +inline constexpr gp::StringView kAppDataScheme = "appdata://"; +inline constexpr gp::StringView kCacheScheme = "cache://"; +inline constexpr gp::StringView kTempScheme = "temp://"; + +/// @brief Stack-allocated buffer holding a normalized lowercase URI scheme prefix (e.g., `"game://"`). +using SchemeBuffer = gp::FixedString; + +/// @brief Result of decomposing and sandbox-validating a logical VFS URI (ADR-0044). +struct ParsedUri +{ +public: + /// @brief Normalized lowercase scheme prefix including `"://"` (e.g., `"game://"`). + SchemeBuffer scheme{}; + + /// @brief Sandbox-validated relative path inside the scheme with all `"."` and `".."` segments collapsed + /// (e.g., `"textures/hero.ktx2"`, or empty for the root of the scheme `"game://"`). + gp::PathBuffer relativePath{}; + +public: + /// @brief Checks whether this parsed URI refers to the bare root of the scheme (e.g., `"game://"`). + /// @return True if `relativePath` is empty, false otherwise. + [[nodiscard]] constexpr bool isSchemeRoot() const noexcept + { + return relativePath.isEmpty(); + } +}; + +/// @brief Descriptor snapshot describing a registered mount point inside `VirtualFileSystem` (ADR-0044). +struct MountPointDesc +{ +public: + /// @brief Normalized lowercase URI scheme bound to this mount (e.g., `"game://"`). + SchemeBuffer scheme{}; + + /// @brief Physical OS root directory or logical backend identifier (e.g., `"C:/Game/Content/"` or `"[memory]"`). + gp::PathBuffer rootPath{}; + + /// @brief Overlay priority tier (`DeveloperOverride` > `ModOverride` > `Patch` > `DLC` > `Base`). + MountPriority priority{ MountPriority::Base }; + + /// @brief Access permission contract (`ReadOnly` vs. `ReadWrite`). + MountAccess access{ MountAccess::ReadOnly }; +}; + +/// @brief Non-owning stack view passed to VFS directory iteration visitors (ADR-0044, ADR-0060). +struct VfsDirectoryEntry +{ +public: + /// @brief Full logical VFS URI of the entry (e.g., `"game://textures/hero.ktx2"`). + gp::StringView uri{}; + + /// @brief Clean leaf filename or directory name without parent path components (e.g., `"hero.ktx2"`). + gp::StringView name{}; + + /// @brief Metadata snapshot (`size`, timestamps, `FileAttributeFlags`). + gp::platform::FileStats stats{}; + + /// @brief Priority of the winning mount backend that provided this entry. + MountPriority sourcePriority{ MountPriority::Base }; + + /// @brief Zero-based recursion depth relative to the queried VFS directory URI. + gp::UInt32 depth{ 0u }; + +public: + /// @brief Checks whether this VFS directory entry is a regular file. + /// @return True if `stats.isFile()`, false otherwise. + [[nodiscard]] constexpr bool isFile() const noexcept + { + return stats.isFile(); + } + + /// @brief Checks whether this VFS directory entry is a directory. + /// @return True if `stats.isDirectory()`, false otherwise. + [[nodiscard]] constexpr bool isDirectory() const noexcept + { + return stats.isDirectory(); + } +}; + +/// @brief Stateless C-style callback signature for zero-allocation VFS mount-table inspection. +/// @param[in] desc Stack-resident snapshot descriptor of an active mount point. +/// @param[in] userData Opaque caller-supplied context pointer. +/// @return True to continue visiting remaining mounts, false to stop early. +using MountPointVisitorFn = bool (*)(const MountPointDesc& desc, void* userData); + +/// @brief Stateless C-style callback signature for zero-allocation VFS directory enumeration. +/// @param[in] entry Stack-resident VFS directory entry descriptor. +/// @param[in] userData Opaque caller-supplied context pointer. +/// @return `gp::platform::DirectoryVisitControl` (`Continue`, `SkipSubdirectory`, or `Stop`). +using VfsDirectoryVisitorFn = gp::platform::DirectoryVisitControl (*)(const VfsDirectoryEntry& entry, void* userData); + +} // namespace gp::vfs diff --git a/source/runtime/core/public/vfs/VirtualFileSystem.hpp b/source/runtime/core/public/vfs/VirtualFileSystem.hpp new file mode 100644 index 00000000..88ad3f99 --- /dev/null +++ b/source/runtime/core/public/vfs/VirtualFileSystem.hpp @@ -0,0 +1,508 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#pragma once + +#include "containers/strings/String.hpp" +#include "containers/views/StringView.hpp" // IWYU pragma: keep +#include "CoreMinimal.hpp" +#include "platforms/base/system/FileEnums.hpp" +#include "platforms/base/system/FileHandle.hpp" +#include "platforms/base/system/FileTypes.hpp" +#include "platforms/base/system/PathTypes.hpp" +#include "templates/Expected.hpp" +#include "vfs/IMountBackend.hpp" +#include "vfs/VfsEnums.hpp" +#include "vfs/VfsTypes.hpp" +#include +#include + +namespace gp::vfs +{ + +/// @brief Layer 1 Priority-Layered Virtual File System and Logical URI Router (`gp::vfs::VirtualFileSystem`) +/// (ADR-0044, ADR-0060). +/// @details Binds logical URI schemes (`engine://`, `game://`, `user://`, `appdata://`, `cache://`, `temp://`) to +/// priority-ordered `IMountBackend` instances (`PhysicalMountBackend`, `MemoryMountBackend`, or custom +/// archive backends). Enforces strict sandbox escape prevention (`VfsError::SandboxEscapeViolation`), +/// priority-ordered read resolution (`DeveloperOverride > ModOverride > Patch > DLC > Base`), single-target +/// write routing to the highest-priority `MountAccess::ReadWrite` mount, and deduplicated multi-mount +/// directory enumeration. +class GP_CORE_API VirtualFileSystem +{ +public: + VirtualFileSystem() = delete; + ~VirtualFileSystem() = delete; + VirtualFileSystem(const VirtualFileSystem&) = delete; + VirtualFileSystem& operator=(const VirtualFileSystem&) = delete; + VirtualFileSystem(VirtualFileSystem&&) = delete; + VirtualFileSystem& operator=(VirtualFileSystem&&) = delete; + +public: + /// @section Lifecycle & Bootstrap Mounting + + /// @brief Mounts the six canonical ADR-0044 URI schemes (`engine://`, `game://`, `user://`, `appdata://`, + /// `cache://`, `temp://`) using Layer 0 `gp::platform::Paths`. + /// @param[in] appName Application subfolder name appended to `documentsDir()`, `appDataDir()`, + /// `localAppDataDir()`, and `tempDir()` (defaults to `Paths::executableName(true)` if empty). + /// @return `Expected` containing `true` on successful bootstrap, or a `VfsError`. + static gp::Expected initializeDefaultMounts(const gp::StringView appName = {}) noexcept; + + /// @brief Unmounts all registered physical and custom backends and resets the VFS mount table. + static void shutdown() noexcept; + + /// @brief Mounts a physical OS directory at `physicalRootDir` onto `scheme` with the specified priority and access. + /// @param[in] scheme Logical URI scheme (e.g., `"game://"` or `"game"`). + /// @param[in] physicalRootDir Physical OS directory path. + /// @param[in] priority Overlay priority tier (`MountPriority::Base`, `ModOverride`, etc.). + /// @param[in] access Read/Write access policy (`MountAccess::ReadOnly` or `MountAccess::ReadWrite`). + /// @return `Expected` containing `true` on success, or `VfsError::MountTableFull` / `InvalidUri`. + static gp::Expected mount( + const gp::StringView scheme, + const gp::StringView physicalRootDir, + const MountPriority priority = MountPriority::Base, + const MountAccess access = MountAccess::ReadOnly + ) noexcept; + + /// @brief Mounts an external or custom `IMountBackend` instance (such as `MemoryMountBackend`) onto `scheme`. + /// @note The caller retains ownership of `*backend`, which must remain alive until unmounted or `shutdown()`. + /// @param[in] scheme Logical URI scheme (e.g., `"game://"`). + /// @param[in] backend Non-null pointer to the `IMountBackend` implementation. + /// @param[in] priority Overlay priority tier. + /// @param[in] access Read/Write access policy. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected mountBackend( + const gp::StringView scheme, + IMountBackend* const backend, + const MountPriority priority = MountPriority::Base, + const MountAccess access = MountAccess::ReadOnly + ) noexcept; + + /// @brief Unmounts a specific physical root directory or backend identifier from `scheme`. + /// @param[in] scheme Logical URI scheme. + /// @param[in] rootPath Physical root directory or backend `rootPath()` identifier to remove. + /// @return True if a matching mount point was found and removed, false otherwise. + static bool unmount(const gp::StringView scheme, const gp::StringView rootPath) noexcept; + + /// @brief Unmounts a specific `IMountBackend` pointer from `scheme`. + /// @param[in] scheme Logical URI scheme. + /// @param[in] backend Pointer to the `IMountBackend` instance to remove. + /// @return True if the backend was found and removed, false otherwise. + static bool unmountBackend(const gp::StringView scheme, const IMountBackend* const backend) noexcept; + + /// @brief Unmounts all mount points currently bound to `scheme`. + /// @param[in] scheme Logical URI scheme to clear. + /// @return Number of mount points removed. + static gp::USize unmountScheme(const gp::StringView scheme) noexcept; + + /// @brief Checks whether at least one mount point is registered for `scheme`. + /// @param[in] scheme Logical URI scheme (e.g., `"game://"` or `"game"`). + /// @return True if `scheme` has one or more active mounts, false otherwise. + [[nodiscard]] static bool isSchemeMounted(const gp::StringView scheme) noexcept; + + /// @brief Returns the total number of active mount points across all schemes (or for a specific `scheme` if + /// non-empty). + /// @param[in] scheme Optional scheme filter (empty view counts all registered mounts). + /// @return Active mount point count. + [[nodiscard]] static gp::USize getMountCount(const gp::StringView scheme = {}) noexcept; + + /// @brief Visits active mount points in deterministic lookup order (sorted by scheme, descending priority, and + /// descending registration order) without heap allocations. + /// @note Holds a shared read lock across the invocation; the visitor must not call mutating VFS APIs + /// (`mount`, `unmount`, `shutdown`). + /// @param[in] scheme Optional scheme filter (empty view visits mounts across all schemes). + /// @param[in] visitor Stateless C callback receiving a `MountPointDesc` snapshot per active mount. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return Number of mount points visited before completion or early stop. + static gp::USize enumerateMounts( + const gp::StringView scheme, const MountPointVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @brief Visits active mount points invoking any C++ callable/lambda `(const MountPointDesc&) -> bool` with + /// zero heap allocations. + /// @note Holds a shared read lock across the invocation; the visitor must not call mutating VFS APIs. + /// @tparam InVisitor Callable matching `bool(const MountPointDesc&)`. + /// @param[in] scheme Optional scheme filter (empty view visits mounts across all schemes). + /// @param[in,out] visitor Callable returning `true` to continue visiting or `false` to stop early. + /// @return Number of mount points visited. + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const MountPointDesc& desc) { + { + fn(desc) + } -> std::same_as; + } + ) + static gp::USize enumerateMounts(const gp::StringView scheme, InVisitor&& visitor) noexcept + { + using VisitorType = std::remove_reference_t; + const MountPointVisitorFn trampoline = [](const MountPointDesc& desc, void* const rawCallable) -> bool + { + VisitorType* const fn = static_cast(rawCallable); + return (*fn)(desc); + }; + return enumerateMounts(scheme, trampoline, const_cast(static_cast(&visitor))); + } + +public: + /// @section URI Parsing, Sandbox Validation & Physical Path Resolution + + /// @brief Normalizes a raw scheme string (`"game"`, `"GAME:"`, `"game://"`) into canonical lowercase `"scheme://"`. + /// @param[in] rawScheme Input scheme string view. + /// @param[out] outScheme Receives the normalized `"scheme://"` prefix. + /// @return True if `rawScheme` is a syntactically valid URI scheme name, false otherwise. + [[nodiscard]] static bool normalizeScheme(const gp::StringView rawScheme, SchemeBuffer& outScheme) noexcept; + + /// @brief Parses a logical URI (`"game://textures/../models/hero.mesh"`) into its canonical scheme and + /// sandbox-validated relative path (ADR-0044 Invariant 1). + /// @param[in] uri Input logical VFS URI. + /// @return `Expected` containing the normalized scheme and collapsed relative path, or + /// `VfsError::SandboxEscapeViolation` / `VfsError::InvalidUri`. + [[nodiscard]] static gp::Expected parseUri(const gp::StringView uri) noexcept; + + /// @brief Resolves a logical URI to a physical OS `PathBuffer` for reading (searching highest-to-lowest priority + /// physical mounts where the file exists, or the highest-priority physical mount if none exists yet). + /// @param[in] uri Logical VFS URI to resolve. + /// @return `Expected` containing the resolved physical OS path. + [[nodiscard]] static gp::Expected resolvePhysicalPath(const gp::StringView uri) noexcept; + + /// @brief Resolves a logical URI to a physical OS `PathBuffer` on the highest-priority `MountAccess::ReadWrite` + /// mount for `uri`'s scheme. + /// @param[in] uri Logical VFS URI to resolve for writing. + /// @return `Expected` containing the writable physical OS path, or + /// `VfsError::ReadOnlyMount`. + [[nodiscard]] static gp::Expected + resolveWritablePhysicalPath(const gp::StringView uri) noexcept; + +public: + /// @section VFS Existence & Metadata Queries + + /// @brief Checks whether a file or directory exists at `uri` in any mounted backend for the scheme. + /// @param[in] uri Logical VFS URI (e.g., `"game://configs/default.ini"`). + /// @return True if the entry exists in at least one mounted layer, false otherwise. + [[nodiscard]] static bool exists(const gp::StringView uri) noexcept; + + /// @brief Checks whether `uri` exists and refers to a regular file in the highest-priority matching mount. + /// @param[in] uri Logical VFS URI. + /// @return True if `uri` exists and is a regular file, false otherwise. + [[nodiscard]] static bool isFile(const gp::StringView uri) noexcept; + + /// @brief Checks whether `uri` exists and refers to a directory in any mounted backend for the scheme. + /// @param[in] uri Logical VFS URI. + /// @return True if `uri` exists and is a directory, false otherwise. + [[nodiscard]] static bool isDirectory(const gp::StringView uri) noexcept; + + /// @brief Queries `FileStats` for `uri` from the highest-priority mounted backend that contains the entry. + /// @param[in] uri Logical VFS URI. + /// @return `Expected` containing the entry's metadata, or `VfsError::NotFound`. + [[nodiscard]] static gp::Expected getStats(const gp::StringView uri) noexcept; + + /// @brief Queries the logical byte size of a regular file at `uri` from the highest-priority matching mount. + /// @param[in] uri Logical VFS URI. + /// @return `Expected` containing the file size in bytes, or a `VfsError`. + [[nodiscard]] static gp::Expected fileSize(const gp::StringView uri) noexcept; + +public: + /// @section VFS File Handle Opening & Mutations + + /// @brief Opens a Layer 0 `FileHandle` for reading from the highest-priority physical mount containing `uri`. + /// @param[in] uri Logical VFS URI to open. + /// @param[in] shareMode Concurrent sharing permissions (defaults to `FileShareMode::ReadWrite`). + /// @return `Expected` containing the open read-only `FileHandle`. + [[nodiscard]] static gp::Expected openRead( + const gp::StringView uri, const gp::platform::FileShareMode shareMode = gp::platform::FileShareMode::ReadWrite + ) noexcept; + + /// @brief Opens a Layer 0 `FileHandle` for writing on the highest-priority `MountAccess::ReadWrite` mount for + /// `uri`'s scheme. + /// @param[in] uri Logical VFS URI to open for writing. + /// @param[in] append If true, appends to the end of the file; if false (default), truncates/creates via + /// `CreateAlways`. + /// @param[in] allowRead If true, opens with `FileAccessMode::ReadWrite`. + /// @param[in] shareMode Concurrent sharing permissions (defaults to `FileShareMode::Read`). + /// @return `Expected` containing the open writable `FileHandle`, or + /// `VfsError::ReadOnlyMount`. + [[nodiscard]] static gp::Expected openWrite( + const gp::StringView uri, + const bool append = false, + const bool allowRead = false, + const gp::platform::FileShareMode shareMode = gp::platform::FileShareMode::Read + ) noexcept; + + /// @brief Creates a single directory at `uri` on the highest-priority `ReadWrite` mount for the scheme. + /// @param[in] uri Logical VFS directory URI. + /// @return `Expected` containing `true` on success, or `VfsError::ReadOnlyMount`. + static gp::Expected createDirectory(const gp::StringView uri) noexcept; + + /// @brief Recursively creates `uri` and all missing parent directories on the highest-priority `ReadWrite` mount. + /// @param[in] uri Logical VFS directory tree URI. + /// @return `Expected` containing `true` on success, or `VfsError::ReadOnlyMount`. + static gp::Expected createDirectoryTree(const gp::StringView uri) noexcept; + + /// @brief Deletes a regular file at `uri` on the highest-priority `ReadWrite` mount containing it. + /// @param[in] uri Logical VFS file URI to remove. + /// @return `Expected` containing `true` on success, or `VfsError::ReadOnlyMount` / `NotFound`. + static gp::Expected removeFile(const gp::StringView uri) noexcept; + + /// @brief Deletes an empty directory at `uri` on the highest-priority `ReadWrite` mount containing it. + /// @param[in] uri Logical VFS directory URI to remove. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected removeDirectory(const gp::StringView uri) noexcept; + + /// @brief Recursively deletes a directory and all its contents at `uri` on the highest-priority `ReadWrite` mount. + /// @param[in] uri Logical VFS root directory URI to remove. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected removeDirectoryTree(const gp::StringView uri) noexcept; + + /// @brief Renames or moves an entry from `sourceUri` to `destinationUri`. + /// @param[in] sourceUri Existing logical VFS URI (must reside on a `ReadWrite` mount). + /// @param[in] destinationUri Target logical VFS URI (must resolve to the same `ReadWrite` mount or support + /// copy+rm). + /// @param[in] overwrite If true (default), replaces any existing target file. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected + move(const gp::StringView sourceUri, const gp::StringView destinationUri, const bool overwrite = true) noexcept; + + /// @brief Copies a file from `sourceUri` (any readable mount, including `ReadOnly` `engine://` or `game://`) to + /// `destinationUri` (any `ReadWrite` mount such as `user://` or `cache://`). + /// @param[in] sourceUri Existing logical VFS file URI. + /// @param[in] destinationUri Target logical VFS file URI on a writable scheme. + /// @param[in] overwrite If true (default), overwrites any existing file at `destinationUri`. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected copyFile( + const gp::StringView sourceUri, const gp::StringView destinationUri, const bool overwrite = true + ) noexcept; + +public: + /// @section Merged Multi-Mount Directory Enumeration + + /// @brief Iterates over the merged children of `directoryUri` across all mounted layers for the scheme, + /// deduplicating shadowed filenames so highest-priority overrides win (ADR-0044). + /// @param[in] directoryUri Logical VFS directory URI (e.g., `"game://textures"` or `"game://"`). + /// @param[in] visitor Stateless C callback invoked once per unique child entry. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return `Expected` containing `true` on completion, or a `VfsError`. + static gp::Expected iterateDirectory( + const gp::StringView directoryUri, const VfsDirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @brief Iterates over the merged children of `directoryUri` invoking any C++ callable/lambda + /// `(const VfsDirectoryEntry&) -> DirectoryVisitControl` with zero heap allocations (ADR-0044, ADR-0060). + /// @tparam InVisitor Callable matching `gp::platform::DirectoryVisitControl(const VfsDirectoryEntry&)`. + /// @param[in] directoryUri Logical VFS directory URI. + /// @param[in,out] visitor Callable invoked once per unique merged child entry. + /// @return `Expected` containing `true` on completion, or a `VfsError`. + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const VfsDirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectory(const gp::StringView directoryUri, InVisitor&& visitor) noexcept + { + using VisitorType = std::remove_reference_t; + const VfsDirectoryVisitorFn trampoline = [](const VfsDirectoryEntry& entry, + void* const rawCallable) -> gp::platform::DirectoryVisitControl + { + VisitorType* const fn = static_cast(rawCallable); + return (*fn)(entry); + }; + return iterateDirectory(directoryUri, trampoline, const_cast(static_cast(&visitor))); + } + + /// @brief Recursively iterates over `directoryUri` and all merged subdirectories in depth-first pre-order. + /// @param[in] directoryUri Logical VFS root directory URI. + /// @param[in] visitor Stateless C callback returning `Continue`, `SkipSubdirectory`, or `Stop`. + /// @param[in] userData Opaque context pointer forwarded to `visitor`. + /// @return `Expected` containing `true` on completion, or a `VfsError`. + static gp::Expected iterateDirectoryRecursive( + const gp::StringView directoryUri, const VfsDirectoryVisitorFn visitor, void* const userData = nullptr + ) noexcept; + + /// @brief Recursively iterates over `directoryUri` invoking any C++ callable/lambda + /// `(const VfsDirectoryEntry&) -> DirectoryVisitControl` with zero heap allocations. + /// @tparam InVisitor Callable matching `gp::platform::DirectoryVisitControl(const VfsDirectoryEntry&)`. + /// @param[in] directoryUri Logical VFS root directory URI. + /// @param[in,out] visitor Callable invoked once per unique visited entry. + /// @return `Expected` containing `true` on completion, or a `VfsError`. + template + requires( + !std::is_convertible_v && + requires(InVisitor& fn, const VfsDirectoryEntry& entry) { + { + fn(entry) + } -> std::same_as; + } + ) static gp::Expected + iterateDirectoryRecursive(const gp::StringView directoryUri, InVisitor&& visitor) noexcept + { + using VisitorType = std::remove_reference_t; + const VfsDirectoryVisitorFn trampoline = [](const VfsDirectoryEntry& entry, + void* const rawCallable) -> gp::platform::DirectoryVisitControl + { + VisitorType* const fn = static_cast(rawCallable); + return (*fn)(entry); + }; + return iterateDirectoryRecursive( + directoryUri, trampoline, const_cast(static_cast(&visitor)) + ); + } + +public: + /// @section Bulk & Crash-Safe Atomic VFS Utilities + + /// @brief Reads up to `bytesToRead` bytes starting at `offset` from `uri` (from the highest-priority mount + /// containing `uri`) into `outBuffer`. + /// @param[in] uri Logical VFS file URI. + /// @param[in] offset Byte offset from the start of the file. + /// @param[out] outBuffer Destination memory buffer. + /// @param[in] bytesToRead Maximum number of bytes to read. + /// @return `Expected` containing the number of bytes read into `outBuffer`. + [[nodiscard]] static gp::Expected readBytesAt( + const gp::StringView uri, const gp::UInt64 offset, void* const outBuffer, const gp::USize bytesToRead + ) noexcept; + + /// @brief Reads up to `bufferCapacity` bytes from the start of `uri` into `outBuffer`. + /// @param[in] uri Logical VFS file URI. + /// @param[out] outBuffer Destination memory buffer. + /// @param[in] bufferCapacity Maximum number of bytes to read. + /// @return `Expected` containing the number of bytes read. + [[nodiscard]] static gp::Expected + readBytes(const gp::StringView uri, void* const outBuffer, const gp::USize bufferCapacity) noexcept; + + /// @brief Reads an entire binary file from `uri` (highest-priority matching mount) into any 1-byte element + /// container (`gp::Vector`, `gp::String`, etc.). + /// @tparam InByteContainer Dynamic byte container type with `sizeof(ValueType) == 1`. + /// @param[in] uri Logical VFS file URI. + /// @param[out] outBuffer Destination byte container resized once and populated with the file payload. + /// @return `Expected` containing the number of bytes read into `outBuffer`. + template + requires(sizeof(typename InByteContainer::ValueType) == 1u) + static gp::Expected readAllBytes(const gp::StringView uri, InByteContainer& outBuffer) noexcept + { + outBuffer.clear(); + const gp::Expected sizeRes = fileSize(uri); + if (!sizeRes.hasValue()) + { + return gp::makeUnexpected(sizeRes.error()); + } + + const gp::USize byteCount = static_cast(sizeRes.value()); + if (byteCount == 0u) + { + return 0u; + } + + if constexpr (requires { outBuffer.resizeUninitialized(byteCount); }) + { + outBuffer.resizeUninitialized(byteCount); + } + else + { + outBuffer.resize(byteCount); + } + + const gp::Expected readRes = readBytesAt(uri, 0ULL, outBuffer.data(), byteCount); + if (!readRes.hasValue()) + { + outBuffer.clear(); + return gp::makeUnexpected(readRes.error()); + } + + if (readRes.value() < byteCount) + { + outBuffer.resize(readRes.value()); + } + + return readRes.value(); + } + + /// @brief Reads an entire UTF-8 text file from `uri` (highest-priority matching mount) into any + /// `gp::container::BasicString`. + /// @tparam InAllocator Engine allocator satisfying `gp::concepts::IsAllocator`. + /// @param[in] uri Logical VFS file URI. + /// @param[out] outString Destination string resized once and populated with the file payload. + /// @return `Expected` containing the number of bytes read into `outString`. + template + static gp::Expected + readAllText(const gp::StringView uri, gp::container::BasicString& outString) noexcept + { + outString.clear(); + const gp::Expected sizeRes = fileSize(uri); + if (!sizeRes.hasValue()) + { + return gp::makeUnexpected(sizeRes.error()); + } + + const gp::USize byteCount = static_cast(sizeRes.value()); + if (byteCount == 0u) + { + return 0u; + } + + outString.resizeUninitialized(byteCount); + const gp::Expected readRes = readBytesAt(uri, 0ULL, outString.data(), byteCount); + if (!readRes.hasValue()) + { + outString.clear(); + return gp::makeUnexpected(readRes.error()); + } + + if (readRes.value() < byteCount) + { + outString.resize(readRes.value()); + } + + return readRes.value(); + } + + /// @brief Writes `sizeInBytes` from `data` to `uri` on the highest-priority `ReadWrite` mount for the scheme. + /// @param[in] uri Logical VFS file URI. + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to write. + /// @return `Expected` containing `true` on success, or `VfsError::ReadOnlyMount`. + static gp::Expected + writeAllBytes(const gp::StringView uri, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Writes a UTF-8 string view `text` to `uri` on the highest-priority `ReadWrite` mount for the scheme. + /// @param[in] uri Logical VFS file URI. + /// @param[in] text UTF-8 text payload to write. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected writeAllText(const gp::StringView uri, const gp::StringView text) noexcept; + + /// @brief Appends `sizeInBytes` from `data` to `uri` on the highest-priority `ReadWrite` mount for the scheme. + /// @param[in] uri Logical VFS file URI. + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to append. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected + appendAllBytes(const gp::StringView uri, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Appends a UTF-8 string view `text` to `uri` on the highest-priority `ReadWrite` mount for the scheme. + /// @param[in] uri Logical VFS file URI. + /// @param[in] text UTF-8 text payload to append. + /// @return `Expected` containing `true` on success, or a `VfsError`. + static gp::Expected appendAllText(const gp::StringView uri, const gp::StringView text) noexcept; + + /// @brief Crash-safe atomic write transaction routed through the highest-priority `ReadWrite` mount for `uri`'s + /// scheme (ADR-0044, ADR-0060). + /// @param[in] uri Logical VFS file URI (e.g., `"user://saves/slot01.sav"`). + /// @param[in] data Source memory buffer. + /// @param[in] sizeInBytes Number of bytes to commit atomically. + /// @return `Expected` containing `true` on atomic commit, or `VfsError::ReadOnlyMount`. + static gp::Expected + writeAtomic(const gp::StringView uri, const void* const data, const gp::USize sizeInBytes) noexcept; + + /// @brief Crash-safe atomic text write overload for `gp::StringView` payloads. + /// @param[in] uri Logical VFS file URI. + /// @param[in] text UTF-8 text payload to commit atomically. + /// @return `Expected` containing `true` on atomic commit, or a `VfsError`. + static gp::Expected writeAtomicText(const gp::StringView uri, const gp::StringView text) noexcept; +}; + +} // namespace gp::vfs diff --git a/source/runtime/core/tests/logging/Logger.tests.cpp b/source/runtime/core/tests/logging/Logger.tests.cpp index 5e7759a2..30129dac 100644 --- a/source/runtime/core/tests/logging/Logger.tests.cpp +++ b/source/runtime/core/tests/logging/Logger.tests.cpp @@ -15,6 +15,7 @@ #include "logging/sinks/StringLogSink.hpp" #include "logging/sinks/TracySink.hpp" #include "miscellaneous/CommandLine.hpp" +#include "platforms/base/system/FileSystem.hpp" #include "platforms/base/system/Paths.hpp" #include "templates/ScopeExit.hpp" // IWYU pragma: keep #include @@ -256,6 +257,67 @@ TEST(LoggerTest, FileSinkWritesAndFlushesToDisk) EXPECT_TRUE(fileContents.contains("[ERROR][LogTestSubsystem] Second disk line 200")); } +TEST(LoggerTest, FileSinkFileHandleCreatesParentsSharesLiveReadAndAppends) +{ + const gp::platform::PathBuffer testRoot = + gp::platform::Paths::combine(gp::platform::Paths::tempDir(), "gp_filesink_handle_test"); + const gp::platform::PathBuffer nestedLogPath = + gp::platform::Paths::combine(testRoot.view(), "nested/subdir/app.log"); + gp::platform::FileSystem::removeDirectoryTree(testRoot.view()); + + auto cleanup = gp::makeScopeExit( + [&testRoot]() noexcept -> void + { + gp::platform::FileSystem::removeDirectoryTree(testRoot.view()); + } + ); + + FileSinkDesc firstDesc{}; + firstDesc.filePath = nestedLogPath.view(); + firstDesc.minLevel = LogLevel::Info; + firstDesc.flags = LogSinkFlags::None; + firstDesc.truncateOnOpen = true; + + FileSink sink{}; + ASSERT_EQ(sink.open(firstDesc), LogResult::Success); + EXPECT_TRUE(sink.isOpen()); + + Logger logger{}; + LoggerDesc loggerDesc{}; + loggerDesc.mode = LogExecutionMode::Synchronous; + loggerDesc.applyCommandLineOverrides = false; + ASSERT_EQ(logger.initialize(loggerDesc), LogResult::Success); + ASSERT_EQ(logger.addSink(&sink), LogResult::Success); + + LogTestSubsystem.setActiveLevel(LogLevel::Info); + GP_LOGGER_LOG(logger, LogTestSubsystem, Info, "Live shared line 1"); + logger.flush(); + + // Verify FileShareMode::Read allows an external reader to inspect the flushed log while FileSink holds it open. + gp::String liveSnapshot{}; + ASSERT_TRUE(gp::platform::FileSystem::readAllText(nestedLogPath.view(), liveSnapshot).hasValue()); + EXPECT_TRUE(liveSnapshot.view().contains("Live shared line 1")); + + // Close and re-open in append mode (`truncateOnOpen = false`), then flush again. + sink.close(); + EXPECT_FALSE(sink.isOpen()); + + FileSinkDesc appendDesc = firstDesc; + appendDesc.truncateOnOpen = false; + ASSERT_EQ(sink.open(appendDesc), LogResult::Success); + EXPECT_TRUE(sink.isOpen()); + + GP_LOGGER_LOG(logger, LogTestSubsystem, Error, "Appended line 2"); + logger.flush(); + sink.close(); + logger.shutdown(); + + gp::String finalContents{}; + ASSERT_TRUE(gp::platform::FileSystem::readAllText(nestedLogPath.view(), finalContents).hasValue()); + EXPECT_TRUE(finalContents.view().contains("Live shared line 1")); + EXPECT_TRUE(finalContents.view().contains("Appended line 2")); +} + TEST(LoggerTest, AsyncRingMultiThreadedConcurrencyStress) { constexpr gp::UInt32 kThreadCount = 4u; diff --git a/source/runtime/core/tests/platforms/base/system/FileSystem.tests.cpp b/source/runtime/core/tests/platforms/base/system/FileSystem.tests.cpp new file mode 100644 index 00000000..cc156fa2 --- /dev/null +++ b/source/runtime/core/tests/platforms/base/system/FileSystem.tests.cpp @@ -0,0 +1,601 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "platforms/base/system/FileSystem.hpp" +#include "memory/allocators/LinearAllocator.hpp" +#include "platforms/base/system/Paths.hpp" +#include "threading/atomics/Atomic.hpp" +#include +#include +#include + +namespace gp::platform::tests +{ + +class FileSystemTest : public ::testing::Test +{ +protected: + PathBuffer m_sandboxRoot{}; + +protected: + void SetUp() noexcept override + { + static gp::thread::Atomic s_sandboxCounter(1u); + const gp::UInt32 id = s_sandboxCounter.fetchAdd(1u, gp::memory::MemoryOrder::Relaxed); + + gp::FixedString<64> folderName("gp_fs_test_sandbox_"); + char digits[16]{}; + gp::UInt32 tempId = id; + gp::USize digitLen = 0u; + do + { + digits[digitLen++] = static_cast('0' + (tempId % 10u)); + tempId /= 10u; + } + while (tempId > 0u); + for (gp::USize i = digitLen; i > 0u; --i) + { + folderName.pushBack(digits[i - 1u]); + } + + m_sandboxRoot = Paths::combine(Paths::tempDir(), folderName.view()); + if (FileSystem::exists(m_sandboxRoot.view())) + { + FileSystem::removeDirectoryTree(m_sandboxRoot.view()); + } + const gp::Expected createRes = FileSystem::createDirectoryTree(m_sandboxRoot.view()); + ASSERT_TRUE(createRes.hasValue()); + } + + void TearDown() noexcept override + { + if (!m_sandboxRoot.isEmpty() && FileSystem::exists(m_sandboxRoot.view())) + { + FileSystem::removeDirectoryTree(m_sandboxRoot.view()); + } + } +}; + +TEST_F(FileSystemTest, DefaultFileHandleIsInvalidAndRejectsOperations) +{ + FileHandle handle{}; + EXPECT_FALSE(handle.isValid()); + EXPECT_FALSE(static_cast(handle)); + EXPECT_EQ(handle.nativeDescriptor(), kInvalidNativeFileDescriptor); + + gp::Byte dummy{ 0 }; + EXPECT_EQ(handle.read(&dummy, 1u).error(), FileError::InvalidHandle); + EXPECT_EQ(handle.write(&dummy, 1u).error(), FileError::InvalidHandle); + EXPECT_EQ(handle.readAt(0ULL, &dummy, 1u).error(), FileError::InvalidHandle); + EXPECT_EQ(handle.writeAt(0ULL, &dummy, 1u).error(), FileError::InvalidHandle); + EXPECT_EQ(handle.seek(0, FileSeekOrigin::Begin).error(), FileError::InvalidHandle); + EXPECT_EQ(handle.tell().error(), FileError::InvalidHandle); + EXPECT_EQ(handle.size().error(), FileError::InvalidHandle); + EXPECT_EQ(handle.flush().error(), FileError::InvalidHandle); + EXPECT_EQ(handle.truncate(0ULL).error(), FileError::InvalidHandle); + EXPECT_TRUE(handle.close().hasValue()); +} + +TEST_F(FileSystemTest, CreateDirectoryAndCreateDirectoryTreeHierarchy) +{ + const PathBuffer singleDir = Paths::combine(m_sandboxRoot.view(), "SingleFolder"); + EXPECT_FALSE(FileSystem::exists(singleDir.view())); + + const gp::Expected mkdirRes = FileSystem::createDirectory(singleDir.view()); + ASSERT_TRUE(mkdirRes.hasValue()); + EXPECT_TRUE(FileSystem::exists(singleDir.view())); + EXPECT_TRUE(FileSystem::isDirectory(singleDir.view())); + EXPECT_FALSE(FileSystem::isFile(singleDir.view())); + + // Idempotent second call on existing directory must succeed + EXPECT_TRUE(FileSystem::createDirectory(singleDir.view()).hasValue()); + + // Deep nested tree creation + const PathBuffer deepDir = Paths::combine(m_sandboxRoot.view(), "LevelA/LevelB/LevelC/LevelD"); + EXPECT_FALSE(FileSystem::exists(deepDir.view())); + ASSERT_TRUE(FileSystem::createDirectoryTree(deepDir.view()).hasValue()); + EXPECT_TRUE(FileSystem::isDirectory(deepDir.view())); + + // Removing non-empty parent with single removeDirectory must fail with DirectoryNotEmpty + const PathBuffer levelA = Paths::combine(m_sandboxRoot.view(), "LevelA"); + const gp::Expected failRm = FileSystem::removeDirectory(levelA.view()); + EXPECT_FALSE(failRm.hasValue()); + EXPECT_EQ(failRm.error(), FileError::DirectoryNotEmpty); + + // Recursive tree removal must clean up everything + ASSERT_TRUE(FileSystem::removeDirectoryTree(levelA.view()).hasValue()); + EXPECT_FALSE(FileSystem::exists(levelA.view())); +} + +TEST_F(FileSystemTest, FileHandleSequentialReadWriteSeekTellTruncateAndMoveSemantics) +{ + const PathBuffer filePath = Paths::combine(m_sandboxRoot.view(), "sequential.bin"); + + gp::Expected openRes = + FileSystem::open(filePath.view(), FileAccessMode::ReadWrite, FileOpenMode::CreateNew, FileShareMode::Read); + ASSERT_TRUE(openRes.hasValue()); + + // Move construction transfers ownership cleanly + FileHandle handle(std::move(openRes.value())); + EXPECT_FALSE(openRes.value().isValid()); + ASSERT_TRUE(handle.isValid()); + + const gp::StringView payload = "GraphicalPlaygroundEngine_Layer0_TestPayload"; + const gp::Expected writeRes = handle.write(payload.data(), payload.size()); + ASSERT_TRUE(writeRes.hasValue()); + EXPECT_EQ(writeRes.value(), payload.size()); + + const gp::Expected tellRes = handle.tell(); + ASSERT_TRUE(tellRes.hasValue()); + EXPECT_EQ(tellRes.value(), static_cast(payload.size())); + + const gp::Expected sizeRes = handle.size(); + ASSERT_TRUE(sizeRes.hasValue()); + EXPECT_EQ(sizeRes.value(), static_cast(payload.size())); + + // Seek back to offset 9 ("Playground...") + const gp::Expected seekRes = handle.seek(9, FileSeekOrigin::Begin); + ASSERT_TRUE(seekRes.hasValue()); + EXPECT_EQ(seekRes.value(), 9ULL); + + char readBuf[16]{}; + const gp::Expected readRes = handle.read(readBuf, 10u); + ASSERT_TRUE(readRes.hasValue()); + EXPECT_EQ(readRes.value(), 10u); + EXPECT_EQ(gp::StringView(readBuf, 10u), gp::StringView("Playground")); + + // Truncate to 9 bytes ("Graphical") + ASSERT_TRUE(handle.truncate(9ULL).hasValue()); + EXPECT_EQ(handle.size().value(), 9ULL); + ASSERT_TRUE(handle.flush().hasValue()); + ASSERT_TRUE(handle.close().hasValue()); + EXPECT_FALSE(handle.isValid()); + + // Verify truncated content via readAllText + gp::String truncatedText{}; + ASSERT_TRUE(FileSystem::readAllText(filePath.view(), truncatedText).hasValue()); + EXPECT_EQ(truncatedText.view(), gp::StringView("Graphical")); +} + +TEST_F(FileSystemTest, PositionalReadAtWriteAtAndMultiThreadedConcurrentReads) +{ + const PathBuffer filePath = Paths::combine(m_sandboxRoot.view(), "positional_blocks.bin"); + constexpr gp::USize kBlockCount = 64u; + constexpr gp::USize kBlockSize = 128u; + + { + gp::Expected writeHandleRes = FileSystem::open( + filePath.view(), FileAccessMode::ReadWrite, FileOpenMode::CreateAlways, FileShareMode::Read + ); + ASSERT_TRUE(writeHandleRes.hasValue()); + FileHandle& wh = writeHandleRes.value(); + + // Write blocks out-of-order using positional writeAt + for (gp::USize idx = kBlockCount; idx > 0u; --idx) + { + const gp::USize blockIndex = idx - 1u; + gp::Byte blockData[kBlockSize]{}; + for (gp::USize b = 0u; b < kBlockSize; ++b) + { + blockData[b] = static_cast((blockIndex * 31u + b) & 0xFFu); + } + + const gp::UInt64 byteOffset = static_cast(blockIndex * kBlockSize); + const gp::Expected wRes = wh.writeAt(byteOffset, blockData, kBlockSize); + ASSERT_TRUE(wRes.hasValue()); + EXPECT_EQ(wRes.value(), kBlockSize); + } + } + + // Open a SINGLE read-only FileHandle and share it across 8 concurrent reader threads using readAt() + gp::Expected sharedReadRes = FileSystem::openRead(filePath.view()); + ASSERT_TRUE(sharedReadRes.hasValue()); + const FileHandle& sharedHandle = sharedReadRes.value(); + + constexpr gp::UInt32 kThreadCount = 8u; + constexpr gp::UInt32 kReadsPerThread = 200u; + gp::thread::Atomic readyCount(0u); + gp::thread::Atomic mismatchCount(0u); + + std::vector workers; + workers.reserve(kThreadCount); + + for (gp::UInt32 t = 0u; t < kThreadCount; ++t) + { + workers.emplace_back( + [&sharedHandle, &readyCount, &mismatchCount, t]() -> void + { + readyCount.fetchAdd(1u, gp::memory::MemoryOrder::AcqRel); + while (readyCount.load(gp::memory::MemoryOrder::Acquire) < kThreadCount) + { + std::this_thread::yield(); + } + + gp::Byte localBuf[kBlockSize]{}; + for (gp::UInt32 iter = 0u; iter < kReadsPerThread; ++iter) + { + const gp::USize blockIndex = static_cast((t * 17u + iter * 13u) % kBlockCount); + const gp::UInt64 offset = static_cast(blockIndex * kBlockSize); + + const gp::Expected rRes = sharedHandle.readAt(offset, localBuf, kBlockSize); + if (!rRes.hasValue() || rRes.value() != kBlockSize) + { + mismatchCount.fetchAdd(1u, gp::memory::MemoryOrder::Relaxed); + continue; + } + + for (gp::USize b = 0u; b < kBlockSize; ++b) + { + const gp::Byte expectedByte = static_cast((blockIndex * 31u + b) & 0xFFu); + if (localBuf[b] != expectedByte) + { + mismatchCount.fetchAdd(1u, gp::memory::MemoryOrder::Relaxed); + break; + } + } + } + } + ); + } + + for (std::thread& worker: workers) + { + worker.join(); + } + + EXPECT_EQ(mismatchCount.load(gp::memory::MemoryOrder::Acquire), 0u); +} + +TEST_F(FileSystemTest, BulkReadWriteAppendAtomicWriteAndArenaStringIntegration) +{ + const PathBuffer textPath = Paths::combine(m_sandboxRoot.view(), "config.ini"); + + ASSERT_TRUE(FileSystem::writeAllText(textPath.view(), "[Renderer]\nVsync=true\n").hasValue()); + ASSERT_TRUE(FileSystem::appendAllText(textPath.view(), "RayTracing=true\n").hasValue()); + + // Read into a LinearAllocator-backed PolymorphicString to verify zero-heap arena interoperability (ADR-0042) + alignas(16) gp::Byte arenaSlab[2048]{}; + gp::memory::LinearAllocator linearArena(arenaSlab, sizeof(arenaSlab)); + gp::PolymorphicString arenaStr{ gp::memory::PolymorphicAllocator(linearArena) }; + + const gp::Expected readRes = FileSystem::readAllText(textPath.view(), arenaStr); + ASSERT_TRUE(readRes.hasValue()); + EXPECT_EQ(arenaStr.view(), gp::StringView("[Renderer]\nVsync=true\nRayTracing=true\n")); + + // Crash-safe writeAtomic replacement over existing file + const gp::StringView atomicPayload = "[Renderer]\nVsync=false\nHDR=true\n"; + ASSERT_TRUE(FileSystem::writeAtomicText(textPath.view(), atomicPayload).hasValue()); + + gp::String verifiedText{}; + ASSERT_TRUE(FileSystem::readAllText(textPath.view(), verifiedText).hasValue()); + EXPECT_EQ(verifiedText.view(), atomicPayload); + + gp::String verifiedBytes{}; + ASSERT_TRUE(FileSystem::readAllBytes(textPath.view(), verifiedBytes).hasValue()); + EXPECT_EQ(verifiedBytes.view(), atomicPayload); + + // Ensure the temporary staging file (.tmp) was cleaned up by the atomic rename + PathBuffer stagingPath(textPath); + stagingPath.append(".tmp"); + EXPECT_FALSE(FileSystem::exists(stagingPath.view())); +} + +TEST_F(FileSystemTest, MoveCopyStatsAndReadOnlyAttributes) +{ + const PathBuffer srcPath = Paths::combine(m_sandboxRoot.view(), "original.txt"); + const PathBuffer copyPath = Paths::combine(m_sandboxRoot.view(), "copied.txt"); + const PathBuffer movedPath = Paths::combine(m_sandboxRoot.view(), "moved.txt"); + + ASSERT_TRUE(FileSystem::writeAllText(srcPath.view(), "HelloFileStats12345").hasValue()); + + const gp::Expected statsRes = FileSystem::getStats(srcPath.view()); + ASSERT_TRUE(statsRes.hasValue()); + EXPECT_TRUE(statsRes.value().isFile()); + EXPECT_FALSE(statsRes.value().isDirectory()); + EXPECT_EQ(statsRes.value().size, 19ULL); + EXPECT_GT(statsRes.value().lastWriteTime.nanoseconds, 0ULL); + EXPECT_EQ(FileSystem::fileSize(srcPath.view()).value(), 19ULL); + + // Copy file + ASSERT_TRUE(FileSystem::copyFile(srcPath.view(), copyPath.view(), false).hasValue()); + EXPECT_TRUE(FileSystem::exists(copyPath.view())); + EXPECT_EQ(FileSystem::fileSize(copyPath.view()).value(), 19ULL); + + // Copy without overwrite must fail with AlreadyExists + EXPECT_EQ(FileSystem::copyFile(srcPath.view(), copyPath.view(), false).error(), FileError::AlreadyExists); + // Copy with overwrite=true must succeed + EXPECT_TRUE(FileSystem::copyFile(srcPath.view(), copyPath.view(), true).hasValue()); + + // Move file + ASSERT_TRUE(FileSystem::move(copyPath.view(), movedPath.view(), true).hasValue()); + EXPECT_FALSE(FileSystem::exists(copyPath.view())); + EXPECT_TRUE(FileSystem::exists(movedPath.view())); + + // Read-only attribute toggling + EXPECT_FALSE(FileSystem::isReadOnly(movedPath.view())); + ASSERT_TRUE(FileSystem::setReadOnly(movedPath.view(), true).hasValue()); + EXPECT_TRUE(FileSystem::isReadOnly(movedPath.view())); + ASSERT_TRUE(FileSystem::setReadOnly(movedPath.view(), false).hasValue()); + EXPECT_FALSE(FileSystem::isReadOnly(movedPath.view())); + + ASSERT_TRUE(FileSystem::removeFile(srcPath.view()).hasValue()); + ASSERT_TRUE(FileSystem::removeFile(movedPath.view()).hasValue()); + EXPECT_FALSE(FileSystem::exists(srcPath.view())); + EXPECT_FALSE(FileSystem::exists(movedPath.view())); +} + +TEST_F(FileSystemTest, ZeroAllocationDirectoryIterationAndRecursiveSkipAndStopControl) +{ + const PathBuffer subA = Paths::combine(m_sandboxRoot.view(), "SubA"); + const PathBuffer subSkipped = Paths::combine(m_sandboxRoot.view(), "SubSkipped"); + ASSERT_TRUE(FileSystem::createDirectoryTree(subA.view()).hasValue()); + ASSERT_TRUE(FileSystem::createDirectoryTree(subSkipped.view()).hasValue()); + + ASSERT_TRUE( + FileSystem::writeAllText(Paths::combine(m_sandboxRoot.view(), "root_file.txt").view(), "root").hasValue() + ); + ASSERT_TRUE(FileSystem::writeAllText(Paths::combine(subA.view(), "child_a.txt").view(), "childA").hasValue()); + ASSERT_TRUE( + FileSystem::writeAllText(Paths::combine(subSkipped.view(), "hidden_child.txt").view(), "skipMe").hasValue() + ); + + struct WalkSummary + { + gp::UInt32 fileCount{ 0u }; + gp::UInt32 dirCount{ 0u }; + bool sawHiddenChild{ false }; + }; + + WalkSummary topSummary{}; + const DirectoryVisitorFn topVisitor = [](const DirectoryEntry& entry, void* const rawCtx) -> DirectoryVisitControl + { + WalkSummary* const sum = static_cast(rawCtx); + if (entry.isDirectory()) + { + ++sum->dirCount; + } + else if (entry.isFile()) + { + ++sum->fileCount; + } + return DirectoryVisitControl::Continue; + }; + + ASSERT_TRUE(FileSystem::iterateDirectory(m_sandboxRoot.view(), topVisitor, &topSummary).hasValue()); + EXPECT_EQ(topSummary.dirCount, 2u); + EXPECT_EQ(topSummary.fileCount, 1u); + + // Recursive walk that skips "SubSkipped" + WalkSummary recSummary{}; + const DirectoryVisitorFn recVisitor = [](const DirectoryEntry& entry, void* const rawCtx) -> DirectoryVisitControl + { + WalkSummary* const sum = static_cast(rawCtx); + if (entry.name == "hidden_child.txt") + { + sum->sawHiddenChild = true; + } + if (entry.isDirectory()) + { + ++sum->dirCount; + if (entry.name == "SubSkipped") + { + return DirectoryVisitControl::SkipSubdirectory; + } + } + else if (entry.isFile()) + { + ++sum->fileCount; + } + return DirectoryVisitControl::Continue; + }; + + ASSERT_TRUE(FileSystem::iterateDirectoryRecursive(m_sandboxRoot.view(), recVisitor, &recSummary).hasValue()); + EXPECT_EQ(recSummary.dirCount, 2u); + EXPECT_EQ(recSummary.fileCount, 2u); // root_file.txt + child_a.txt (hidden_child.txt was skipped!) + EXPECT_FALSE(recSummary.sawHiddenChild); + + // Ergonomic C++23 capturing lambda overload + early Stop verification + gp::UInt32 lambdaVisited = 0u; + const gp::Expected stopRes = FileSystem::iterateDirectoryRecursive( + m_sandboxRoot.view(), + [&lambdaVisited](const DirectoryEntry&) -> DirectoryVisitControl + { + ++lambdaVisited; + return (lambdaVisited == 2u) ? DirectoryVisitControl::Stop : DirectoryVisitControl::Continue; + } + ); + ASSERT_TRUE(stopRes.hasValue()); + EXPECT_EQ(lambdaVisited, 2u); +} + +TEST_F(FileSystemTest, OpenModesErrorPathsAndSeekOriginsEdgeCases) +{ + const PathBuffer missingPath = Paths::combine(m_sandboxRoot.view(), "does_not_exist.bin"); + const PathBuffer testFile = Paths::combine(m_sandboxRoot.view(), "modes_test.bin"); + const PathBuffer testDir = Paths::combine(m_sandboxRoot.view(), "a_directory"); + ASSERT_TRUE(FileSystem::createDirectory(testDir.view()).hasValue()); + + // OpenExisting on missing file -> NotFound + EXPECT_EQ(FileSystem::openRead(missingPath.view()).error(), FileError::NotFound); + EXPECT_EQ(FileSystem::fileSize(missingPath.view()).error(), FileError::NotFound); + EXPECT_EQ(FileSystem::getStats(missingPath.view()).error(), FileError::NotFound); + EXPECT_EQ(FileSystem::removeFile(missingPath.view()).error(), FileError::NotFound); + EXPECT_EQ(FileSystem::removeDirectory(missingPath.view()).error(), FileError::NotFound); + + // Operations on directory vs regular file type mismatches + EXPECT_EQ(FileSystem::openRead(testDir.view()).error(), FileError::IsDirectory); + EXPECT_EQ(FileSystem::fileSize(testDir.view()).error(), FileError::IsDirectory); + EXPECT_EQ(FileSystem::removeFile(testDir.view()).error(), FileError::IsDirectory); + EXPECT_EQ(FileSystem::copyFile(testDir.view(), testFile.view(), true).error(), FileError::IsDirectory); + + // CreateNew succeeds once, then fails with AlreadyExists + { + gp::Expected created = + FileSystem::open(testFile.view(), FileAccessMode::ReadWrite, FileOpenMode::CreateNew, FileShareMode::Read); + ASSERT_TRUE(created.hasValue()); + ASSERT_TRUE(created.value().write("0123456789", 10u).hasValue()); + + // Seek relative to Current and End + EXPECT_EQ(created.value().seek(-4, FileSeekOrigin::Current).value(), 6ULL); + EXPECT_EQ(created.value().seek(-2, FileSeekOrigin::End).value(), 8ULL); + char tail[2]{}; + EXPECT_EQ(created.value().read(tail, 2u).value(), 2u); + EXPECT_EQ(gp::StringView(tail, 2u), gp::StringView("89")); + + // Zero-length read/write and null buffer validation + EXPECT_EQ(created.value().read(nullptr, 0u).value(), 0u); + EXPECT_EQ(created.value().write(nullptr, 0u).value(), 0u); + EXPECT_EQ(created.value().read(nullptr, 4u).error(), FileError::InvalidArgument); + EXPECT_EQ(created.value().write(nullptr, 4u).error(), FileError::InvalidArgument); + EXPECT_EQ(created.value().readAt(0ULL, nullptr, 4u).error(), FileError::InvalidArgument); + EXPECT_EQ(created.value().writeAt(0ULL, nullptr, 4u).error(), FileError::InvalidArgument); + + // Read past EOF returns 0 bytes (not an error) + EXPECT_EQ(created.value().readAt(500ULL, tail, 2u).value(), 0u); + } + + EXPECT_EQ( + FileSystem::open(testFile.view(), FileAccessMode::Write, FileOpenMode::CreateNew, FileShareMode::None).error(), + FileError::AlreadyExists + ); + + // OpenAlways preserves existing content without truncating + { + gp::Expected existing = + FileSystem::open(testFile.view(), FileAccessMode::ReadWrite, FileOpenMode::OpenAlways, FileShareMode::Read); + ASSERT_TRUE(existing.hasValue()); + EXPECT_EQ(existing.value().size().value(), 10ULL); + } + + // Regular file passed to directory APIs -> NotDirectory / AlreadyExists + EXPECT_EQ(FileSystem::createDirectory(testFile.view()).error(), FileError::AlreadyExists); + EXPECT_EQ(FileSystem::removeDirectory(testFile.view()).error(), FileError::NotDirectory); + EXPECT_EQ(FileSystem::iterateDirectory(testFile.view(), nullptr, nullptr).error(), FileError::InvalidArgument); + EXPECT_EQ( + FileSystem::iterateDirectory( + testFile.view(), + [](const DirectoryEntry&, void*) -> DirectoryVisitControl + { + return DirectoryVisitControl::Continue; + } + ).error(), + FileError::NotDirectory + ); + + // Empty / invalid paths and self-copy rejection + EXPECT_EQ(FileSystem::openRead("").error(), FileError::InvalidPath); + EXPECT_EQ(FileSystem::createDirectory("").error(), FileError::InvalidPath); + EXPECT_EQ(FileSystem::createDirectoryTree("").error(), FileError::InvalidPath); + EXPECT_EQ(FileSystem::copyFile(testFile.view(), testFile.view(), true).error(), FileError::InvalidArgument); + EXPECT_EQ(FileSystem::move(testFile.view(), testDir.view(), false).error(), FileError::AlreadyExists); + + // FileError::toString constexpr verification + static_assert(toString(FileError::None) == "None"); + static_assert(toString(FileError::NotFound) == "NotFound"); + static_assert(toString(FileError::DiskFull) == "DiskFull"); + EXPECT_EQ(toString(FileError::SharingViolation), gp::StringView("SharingViolation")); +} + +TEST_F(FileSystemTest, ConcurrentWriteAtomicAndEmptyFileEdgeCases) +{ + const PathBuffer emptyPath = Paths::combine(m_sandboxRoot.view(), "empty.dat"); + ASSERT_TRUE(FileSystem::writeAllBytes(emptyPath.view(), nullptr, 0u).hasValue()); + EXPECT_TRUE(FileSystem::isFile(emptyPath.view())); + EXPECT_EQ(FileSystem::fileSize(emptyPath.view()).value(), 0ULL); + + gp::String emptyRead("non_empty_before_read"); + ASSERT_TRUE(FileSystem::readAllText(emptyPath.view(), emptyRead).hasValue()); + EXPECT_TRUE(emptyRead.isEmpty()); + + // Multi-threaded concurrent writeAtomic to the SAME target path must never collide on staging files or corrupt + // the file (every reader must see either a complete payload A or complete payload B, never torn/empty). + const PathBuffer sharedSave = Paths::combine(m_sandboxRoot.view(), "concurrent_save.json"); + const gp::StringView payloadA = "{\"slot\":1,\"checksum\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}"; + const gp::StringView payloadB = "{\"slot\":2,\"checksum\":\"BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB\"}"; + ASSERT_TRUE(FileSystem::writeAtomicText(sharedSave.view(), payloadA).hasValue()); + + constexpr gp::UInt32 kWriterThreads = 4u; + constexpr gp::UInt32 kWritesPerThread = 25u; + gp::thread::Atomic startLatch(0u); + gp::thread::Atomic tornReads(0u); + + std::vector threads; + threads.reserve(kWriterThreads); + for (gp::UInt32 t = 0u; t < kWriterThreads; ++t) + { + threads.emplace_back( + [&sharedSave, &startLatch, &tornReads, payloadA, payloadB, t]() -> void + { + startLatch.fetchAdd(1u, gp::memory::MemoryOrder::AcqRel); + while (startLatch.load(gp::memory::MemoryOrder::Acquire) < kWriterThreads) + { + std::this_thread::yield(); + } + + for (gp::UInt32 i = 0u; i < kWritesPerThread; ++i) + { + const gp::StringView chosen = ((t + i) % 2u == 0u) ? payloadA : payloadB; + // On Windows, simultaneous MoveFileExW replace over the same file can transiently return + // AccessDenied/SharingViolation under extreme contention; what matters is zero corruption and + // zero leaked .tmp.* files. + FileSystem::writeAtomicText(sharedSave.view(), chosen); + + gp::String snapshot{}; + const gp::Expected r = FileSystem::readAllText(sharedSave.view(), snapshot); + if (r.hasValue() && snapshot.view() != payloadA && snapshot.view() != payloadB) + { + tornReads.fetchAdd(1u, gp::memory::MemoryOrder::Relaxed); + } + } + } + ); + } + + for (std::thread& th: threads) + { + th.join(); + } + + EXPECT_EQ(tornReads.load(gp::memory::MemoryOrder::Acquire), 0u); + + // Verify no leaked .tmp.* staging files remain in the sandbox directory + gp::UInt32 leftoverTempFiles = 0u; + ASSERT_TRUE( + FileSystem::iterateDirectory( + m_sandboxRoot.view(), + [&leftoverTempFiles](const DirectoryEntry& entry) -> DirectoryVisitControl + { + if (entry.name.contains(".tmp.")) + { + ++leftoverTempFiles; + } + return DirectoryVisitControl::Continue; + } + ).hasValue() + ); + EXPECT_EQ(leftoverTempFiles, 0u); +} + +TEST_F(FileSystemTest, UnicodeUtf8FilenamesAndReadOnlyTreeDeletion) +{ + const PathBuffer utf8Dir = Paths::combine(m_sandboxRoot.view(), "Assets_日本語_éàü"); + ASSERT_TRUE(FileSystem::createDirectoryTree(utf8Dir.view()).hasValue()); + EXPECT_TRUE(FileSystem::isDirectory(utf8Dir.view())); + + const PathBuffer utf8File = Paths::combine(utf8Dir.view(), "héros_テクスチャ.txt"); + ASSERT_TRUE(FileSystem::writeAllText(utf8File.view(), "UTF-8 payload ✓").hasValue()); + EXPECT_TRUE(FileSystem::isFile(utf8File.view())); + + gp::String readBack{}; + ASSERT_TRUE(FileSystem::readAllText(utf8File.view(), readBack).hasValue()); + EXPECT_EQ(readBack.view(), gp::StringView("UTF-8 payload ✓")); + + // Mark file read-only and verify removeDirectoryTree clears the attribute and succeeds cleanly + ASSERT_TRUE(FileSystem::setReadOnly(utf8File.view(), true).hasValue()); + EXPECT_TRUE(FileSystem::isReadOnly(utf8File.view())); + ASSERT_TRUE(FileSystem::removeDirectoryTree(utf8Dir.view()).hasValue()); + EXPECT_FALSE(FileSystem::exists(utf8Dir.view())); +} + +} // namespace gp::platform::tests diff --git a/source/runtime/core/tests/vfs/VirtualFileSystem.tests.cpp b/source/runtime/core/tests/vfs/VirtualFileSystem.tests.cpp new file mode 100644 index 00000000..72b8baaa --- /dev/null +++ b/source/runtime/core/tests/vfs/VirtualFileSystem.tests.cpp @@ -0,0 +1,661 @@ +// Copyright (c) - Graphical Playground. All rights reserved. +// For more information, see https://graphical-playground/legal +// mailto:support AT graphical-playground DOT com + +#include "vfs/VirtualFileSystem.hpp" +#include "console/ConsoleEnums.hpp" +#include "console/ConsoleTypes.hpp" +#include "console/IConsoleManager.hpp" +#include "platforms/base/system/FileSystem.hpp" +#include "platforms/base/system/Paths.hpp" +#include "threading/atomics/Atomic.hpp" +#include "vfs/MemoryMountBackend.hpp" +#include + +namespace gp::vfs::tests +{ + +class VirtualFileSystemTest : public ::testing::Test +{ +protected: + gp::PathBuffer m_sandboxRoot{}; + gp::PathBuffer m_baseGameDir{}; + gp::PathBuffer m_patchDir{}; + gp::PathBuffer m_modDir{}; + gp::PathBuffer m_userSaveDir{}; + +protected: + void SetUp() noexcept override + { + VirtualFileSystem::shutdown(); + + static gp::thread::Atomic s_vfsSandboxId(1u); + const gp::UInt32 id = s_vfsSandboxId.fetchAdd(1u, gp::memory::MemoryOrder::Relaxed); + + gp::FixedString<64> folderName("gp_vfs_test_sandbox_"); + char digits[16]{}; + gp::UInt32 tempId = id; + gp::USize digitLen = 0u; + do + { + digits[digitLen++] = static_cast('0' + (tempId % 10u)); + tempId /= 10u; + } + while (tempId > 0u); + for (gp::USize i = digitLen; i > 0u; --i) + { + folderName.pushBack(digits[i - 1u]); + } + + m_sandboxRoot = gp::platform::Paths::combine(gp::platform::Paths::tempDir(), folderName.view()); + if (gp::platform::FileSystem::exists(m_sandboxRoot.view())) + { + gp::platform::FileSystem::removeDirectoryTree(m_sandboxRoot.view()); + } + + m_baseGameDir = gp::platform::Paths::combine(m_sandboxRoot.view(), "BaseGame"); + m_patchDir = gp::platform::Paths::combine(m_sandboxRoot.view(), "Patch_1_01"); + m_modDir = gp::platform::Paths::combine(m_sandboxRoot.view(), "Mod_HD"); + m_userSaveDir = gp::platform::Paths::combine(m_sandboxRoot.view(), "UserSaves"); + + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(m_baseGameDir.view()).hasValue()); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(m_patchDir.view()).hasValue()); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(m_modDir.view()).hasValue()); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(m_userSaveDir.view()).hasValue()); + } + + void TearDown() noexcept override + { + VirtualFileSystem::shutdown(); + if (!m_sandboxRoot.isEmpty() && gp::platform::FileSystem::exists(m_sandboxRoot.view())) + { + gp::platform::FileSystem::removeDirectoryTree(m_sandboxRoot.view()); + } + } +}; + +TEST_F(VirtualFileSystemTest, UriParsingAndSandboxJailRejectDirectoryTraversal) +{ + // Valid nested relative collapse inside the sandbox + const gp::Expected validUri = + VirtualFileSystem::parseUri("GAME://textures/characters/../weapons/sword.ktx2"); + ASSERT_TRUE(validUri.hasValue()); + EXPECT_EQ(validUri.value().scheme.view(), gp::StringView("game://")); + EXPECT_EQ(validUri.value().relativePath.view(), gp::StringView("textures/weapons/sword.ktx2")); + + // Root scheme URI + const gp::Expected rootUri = VirtualFileSystem::parseUri("engine://"); + ASSERT_TRUE(rootUri.hasValue()); + EXPECT_EQ(rootUri.value().scheme.view(), gp::StringView("engine://")); + EXPECT_TRUE(rootUri.value().isSchemeRoot()); + + // Direct escape attempts via leading ".." or net-negative ".." must fail with SandboxEscapeViolation (ADR-0044) + EXPECT_EQ(VirtualFileSystem::parseUri("game://../secret.ini").error(), VfsError::SandboxEscapeViolation); + EXPECT_EQ( + VirtualFileSystem::parseUri("game://textures/../../outside.txt").error(), VfsError::SandboxEscapeViolation + ); + EXPECT_EQ(VirtualFileSystem::parseUri("user://C:/Windows/System32").error(), VfsError::SandboxEscapeViolation); + + // Malformed URIs without scheme + EXPECT_EQ(VirtualFileSystem::parseUri("textures/hero.ktx2").error(), VfsError::InvalidUri); + EXPECT_EQ(VirtualFileSystem::parseUri("://missing_scheme").error(), VfsError::InvalidUri); + EXPECT_EQ(VirtualFileSystem::parseUri("").error(), VfsError::InvalidUri); +} + +TEST_F(VirtualFileSystemTest, PriorityLayeredOverlayReadsAndReadOnlyVsReadWriteEnforcement) +{ + // Populate Base, Patch, and Mod directories with overlapping files + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_baseGameDir.view(), "balance.cfg").view(), "version=base" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_baseGameDir.view(), "base_only.txt").view(), "from_base" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_patchDir.view(), "balance.cfg").view(), "version=patch_1_01" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_modDir.view(), "balance.cfg").view(), "version=mod_hd" + ) + .hasValue() + ); + + // Mount Base and Mod out-of-order to verify priority sorting (Mod > Patch > Base) + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_baseGameDir.view(), MountPriority::Base, MountAccess::ReadOnly).hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_modDir.view(), MountPriority::ModOverride, MountAccess::ReadOnly) + .hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_patchDir.view(), MountPriority::Patch, MountAccess::ReadOnly).hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("user://", m_userSaveDir.view(), MountPriority::Base, MountAccess::ReadWrite) + .hasValue() + ); + + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted("game://")); + EXPECT_EQ(VirtualFileSystem::getMountCount("game://"), 3u); + + // Reading "game://balance.cfg" must return the highest-priority ModOverride version + gp::String content{}; + ASSERT_TRUE(VirtualFileSystem::readAllText("game://balance.cfg", content).hasValue()); + EXPECT_EQ(content.view(), gp::StringView("version=mod_hd")); + + // Unmounting ModOverride falls back transparently to Patch + EXPECT_TRUE(VirtualFileSystem::unmount("game://", m_modDir.view())); + ASSERT_TRUE(VirtualFileSystem::readAllText("game://balance.cfg", content).hasValue()); + EXPECT_EQ(content.view(), gp::StringView("version=patch_1_01")); + + // Base-only file is still accessible through the fallback layer + ASSERT_TRUE(VirtualFileSystem::readAllText("game://base_only.txt", content).hasValue()); + EXPECT_EQ(content.view(), gp::StringView("from_base")); + + // Attempting to write, mkdir, or delete on ReadOnly "game://" must fail with ReadOnlyMount (ADR-0044) + EXPECT_EQ(VirtualFileSystem::writeAllText("game://hack.txt", "illegal").error(), VfsError::ReadOnlyMount); + EXPECT_EQ(VirtualFileSystem::writeAtomicText("game://hack.txt", "illegal").error(), VfsError::ReadOnlyMount); + EXPECT_EQ(VirtualFileSystem::createDirectory("game://new_dir").error(), VfsError::ReadOnlyMount); + EXPECT_EQ(VirtualFileSystem::removeFile("game://base_only.txt").error(), VfsError::ReadOnlyMount); + + // Writing and atomic writing to ReadWrite "user://" must succeed + ASSERT_TRUE(VirtualFileSystem::createDirectoryTree("user://profiles/slot1").hasValue()); + ASSERT_TRUE(VirtualFileSystem::writeAtomicText("user://profiles/slot1/save.dat", "SaveData_V1").hasValue()); + ASSERT_TRUE(VirtualFileSystem::readAllText("user://profiles/slot1/save.dat", content).hasValue()); + EXPECT_EQ(content.view(), gp::StringView("SaveData_V1")); + + // Cross-scheme copy from ReadOnly "game://" to ReadWrite "user://" + ASSERT_TRUE(VirtualFileSystem::copyFile("game://base_only.txt", "user://copied_from_game.txt", true).hasValue()); + ASSERT_TRUE(VirtualFileSystem::readAllText("user://copied_from_game.txt", content).hasValue()); + EXPECT_EQ(content.view(), gp::StringView("from_base")); +} + +TEST_F(VirtualFileSystemTest, MergedDirectoryEnumerationDeduplicatesShadowedFilesAcrossLayers) +{ + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_baseGameDir.view(), "shared.txt").view(), "base_shared" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_baseGameDir.view(), "only_base.txt").view(), "base_unique" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_modDir.view(), "shared.txt").view(), "mod_shared_override" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_modDir.view(), "only_mod.txt").view(), "mod_unique" + ) + .hasValue() + ); + + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_baseGameDir.view(), MountPriority::Base, MountAccess::ReadOnly).hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_modDir.view(), MountPriority::ModOverride, MountAccess::ReadOnly) + .hasValue() + ); + + struct MergedWalkResult + { + gp::UInt32 totalVisited{ 0u }; + gp::UInt32 sharedVisitedCount{ 0u }; + MountPriority sharedWinningPriority{ MountPriority::Base }; + gp::UInt64 sharedWinningSize{ 0ULL }; + }; + + MergedWalkResult walk{}; + const VfsDirectoryVisitorFn visitor = [](const VfsDirectoryEntry& entry, + void* const rawCtx) -> gp::platform::DirectoryVisitControl + { + MergedWalkResult* const res = static_cast(rawCtx); + ++res->totalVisited; + if (entry.name == "shared.txt") + { + ++res->sharedVisitedCount; + res->sharedWinningPriority = entry.sourcePriority; + res->sharedWinningSize = entry.stats.size; + } + return gp::platform::DirectoryVisitControl::Continue; + }; + + ASSERT_TRUE(VirtualFileSystem::iterateDirectory("game://", visitor, &walk).hasValue()); + EXPECT_EQ(walk.totalVisited, 3u); // shared.txt + only_base.txt + only_mod.txt + EXPECT_EQ(walk.sharedVisitedCount, 1u); // shared.txt must be emitted once, not twice! + EXPECT_EQ(walk.sharedWinningPriority, MountPriority::ModOverride); + EXPECT_EQ(walk.sharedWinningSize, 19ULL); // strlen("mod_shared_override") +} + +TEST_F(VirtualFileSystemTest, InMemoryMountBackendSupportsFullZeroDiskVfsOperations) +{ + MemoryMountBackend memoryDisk("[memory:unit_test]"); + ASSERT_TRUE( + VirtualFileSystem::mountBackend("cache://", &memoryDisk, MountPriority::Base, MountAccess::ReadWrite).hasValue() + ); + + ASSERT_TRUE(VirtualFileSystem::createDirectoryTree("cache://shaders/dxil/sm6_6").hasValue()); + EXPECT_TRUE(VirtualFileSystem::isDirectory("cache://shaders/dxil/sm6_6")); + + ASSERT_TRUE(VirtualFileSystem::writeAllText("cache://shaders/dxil/sm6_6/pbr.bin", "DXIL_BYTECODE_V1").hasValue()); + EXPECT_TRUE(VirtualFileSystem::exists("cache://shaders/dxil/sm6_6/pbr.bin")); + EXPECT_TRUE(VirtualFileSystem::isFile("cache://shaders/dxil/sm6_6/pbr.bin")); + EXPECT_EQ(VirtualFileSystem::fileSize("cache://shaders/dxil/sm6_6/pbr.bin").value(), 16ULL); + + // Move & Copy inside MemoryMountBackend + ASSERT_TRUE( + VirtualFileSystem::copyFile( + "cache://shaders/dxil/sm6_6/pbr.bin", "cache://shaders/dxil/sm6_6/pbr_copy.bin", false + ) + .hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::move( + "cache://shaders/dxil/sm6_6/pbr_copy.bin", "cache://shaders/dxil/sm6_6/pbr_moved.bin", false + ) + .hasValue() + ); + EXPECT_FALSE(VirtualFileSystem::exists("cache://shaders/dxil/sm6_6/pbr_copy.bin")); + EXPECT_TRUE(VirtualFileSystem::exists("cache://shaders/dxil/sm6_6/pbr_moved.bin")); + + gp::String readBack{}; + ASSERT_TRUE(VirtualFileSystem::readAllText("cache://shaders/dxil/sm6_6/pbr_moved.bin", readBack).hasValue()); + EXPECT_EQ(readBack.view(), gp::StringView("DXIL_BYTECODE_V1")); + + gp::String readBackBytes{}; + ASSERT_TRUE(VirtualFileSystem::readAllBytes("cache://shaders/dxil/sm6_6/pbr_moved.bin", readBackBytes).hasValue()); + EXPECT_EQ(readBackBytes.view(), gp::StringView("DXIL_BYTECODE_V1")); + + // Recursive removal inside MemoryMountBackend + ASSERT_TRUE(VirtualFileSystem::removeDirectoryTree("cache://shaders").hasValue()); + EXPECT_FALSE(VirtualFileSystem::exists("cache://shaders/dxil/sm6_6/pbr.bin")); + EXPECT_FALSE(VirtualFileSystem::exists("cache://shaders")); + + EXPECT_TRUE(VirtualFileSystem::unmountBackend("cache://", &memoryDisk)); +} + +TEST_F(VirtualFileSystemTest, InitializeDefaultMountsRegistersAllSixCanonicalSchemes) +{ + ASSERT_TRUE(VirtualFileSystem::initializeDefaultMounts("GraphicalPlaygroundTest").hasValue()); + + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kEngineScheme)); + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kGameScheme)); + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kUserScheme)); + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kAppDataScheme)); + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kCacheScheme)); + EXPECT_TRUE(VirtualFileSystem::isSchemeMounted(kTempScheme)); + + // engine:// and game:// are ReadOnly by default; user://, appdata://, cache://, temp:// are ReadWrite + EXPECT_EQ(VirtualFileSystem::resolveWritablePhysicalPath("engine://test.txt").error(), VfsError::ReadOnlyMount); + EXPECT_EQ(VirtualFileSystem::resolveWritablePhysicalPath("game://test.txt").error(), VfsError::ReadOnlyMount); + EXPECT_TRUE(VirtualFileSystem::resolveWritablePhysicalPath("user://saves/01.sav").hasValue()); + EXPECT_TRUE(VirtualFileSystem::resolveWritablePhysicalPath("appdata://settings.json").hasValue()); + EXPECT_TRUE(VirtualFileSystem::resolveWritablePhysicalPath("cache://pso.bin").hasValue()); + EXPECT_TRUE(VirtualFileSystem::resolveWritablePhysicalPath("temp://crash.dmp").hasValue()); +} + +TEST_F(VirtualFileSystemTest, RecursiveMergedWalkShadowingFileOverDirAndCrossMountEdgeCases) +{ + // Base has directory "levels/chapter1" with two files + "shadowed_dir/a.txt" + const gp::PathBuffer baseLvl = gp::platform::Paths::combine(m_baseGameDir.view(), "levels/chapter1"); + const gp::PathBuffer baseShadowDir = gp::platform::Paths::combine(m_baseGameDir.view(), "shadowed_dir"); + const gp::PathBuffer modLvl = gp::platform::Paths::combine(m_modDir.view(), "levels/chapter1"); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(baseLvl.view()).hasValue()); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(baseShadowDir.view()).hasValue()); + ASSERT_TRUE(gp::platform::FileSystem::createDirectoryTree(modLvl.view()).hasValue()); + + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText(gp::platform::Paths::combine(baseLvl.view(), "map.bin").view(), "base") + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(baseLvl.view(), "ambient.ogg").view(), "sound" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText(gp::platform::Paths::combine(baseShadowDir.view(), "a.txt").view(), "a") + .hasValue() + ); + // Mod overrides "levels/chapter1/map.bin" AND shadows "shadowed_dir" with a regular file! + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(modLvl.view(), "map.bin").view(), "mod_override" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_modDir.view(), "shadowed_dir").view(), "not_a_dir" + ) + .hasValue() + ); + + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_baseGameDir.view(), MountPriority::Base, MountAccess::ReadOnly).hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_modDir.view(), MountPriority::ModOverride, MountAccess::ReadOnly) + .hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("user://", m_userSaveDir.view(), MountPriority::Base, MountAccess::ReadWrite) + .hasValue() + ); + + // Iterating a URI shadowed by a higher-priority regular file must fail with NotDirectory (no base dir leak!) + EXPECT_EQ( + VirtualFileSystem::iterateDirectory( + "game://shadowed_dir", + [](const VfsDirectoryEntry&) -> gp::platform::DirectoryVisitControl + { + return gp::platform::DirectoryVisitControl::Continue; + } + ).error(), + VfsError::NotDirectory + ); + + // Recursive merged walk over "game://levels" using lambda overload + gp::UInt32 dirVisits = 0u; + gp::UInt32 fileVisits = 0u; + gp::UInt32 maxDepthSeen = 0u; + MountPriority mapPriority = MountPriority::Base; + + ASSERT_TRUE( + VirtualFileSystem::iterateDirectoryRecursive( + "game://levels", + [&dirVisits, &fileVisits, &maxDepthSeen, &mapPriority](const VfsDirectoryEntry& entry) + -> gp::platform::DirectoryVisitControl + { + if (entry.depth > maxDepthSeen) + { + maxDepthSeen = entry.depth; + } + if (entry.isDirectory()) + { + ++dirVisits; + } + else if (entry.isFile()) + { + ++fileVisits; + if (entry.name == "map.bin") + { + mapPriority = entry.sourcePriority; + } + } + return gp::platform::DirectoryVisitControl::Continue; + } + ).hasValue() + ); + EXPECT_EQ(dirVisits, 1u); // chapter1 (deduplicated across Base + Mod!) + EXPECT_EQ(fileVisits, 2u); // map.bin (deduplicated) + ambient.ogg + EXPECT_EQ(maxDepthSeen, 1u); + EXPECT_EQ(mapPriority, MountPriority::ModOverride); + + // Unmounted scheme errors + EXPECT_EQ(VirtualFileSystem::getStats("unknown://file.txt").error(), VfsError::SchemeNotMounted); + EXPECT_EQ(VirtualFileSystem::openRead("unknown://file.txt").error(), VfsError::SchemeNotMounted); + EXPECT_EQ(VirtualFileSystem::writeAllText("unknown://file.txt", "x").error(), VfsError::SchemeNotMounted); + + // Cross-mount move between two different ReadWrite schemes must return CrossMountOperation + MemoryMountBackend tempMem("[memory:cross_move]"); + ASSERT_TRUE( + VirtualFileSystem::mountBackend("temp://", &tempMem, MountPriority::Base, MountAccess::ReadWrite).hasValue() + ); + ASSERT_TRUE(VirtualFileSystem::writeAllText("user://src.txt", "hello").hasValue()); + EXPECT_EQ(VirtualFileSystem::move("user://src.txt", "temp://dst.txt", true).error(), VfsError::CrossMountOperation); + + // Multi-chunk cross-mount copy (> 16 KiB) between PhysicalMountBackend and MemoryMountBackend + gp::String largePayload{}; + largePayload.reserve(40000u); + for (gp::USize i = 0u; i < 40000u; ++i) + { + largePayload.pushBack(static_cast('A' + (i % 26u))); + } + ASSERT_TRUE(VirtualFileSystem::writeAllText("user://large.bin", largePayload.view()).hasValue()); + ASSERT_TRUE(VirtualFileSystem::copyFile("user://large.bin", "temp://large_mem.bin", false).hasValue()); + ASSERT_TRUE(VirtualFileSystem::copyFile("temp://large_mem.bin", "user://large_roundtrip.bin", false).hasValue()); + + gp::String roundTrip{}; + ASSERT_TRUE(VirtualFileSystem::readAllText("user://large_roundtrip.bin", roundTrip).hasValue()); + EXPECT_EQ(roundTrip.view(), largePayload.view()); + + // MemoryMountBackend directory move reparents descendants cleanly and rejects moving into itself + ASSERT_TRUE(VirtualFileSystem::createDirectoryTree("temp://dirA/nested").hasValue()); + ASSERT_TRUE(VirtualFileSystem::writeAllText("temp://dirA/nested/item.txt", "nested_payload").hasValue()); + EXPECT_EQ( + VirtualFileSystem::move("temp://dirA", "temp://dirA/nested/sub", true).error(), VfsError::InvalidArgument + ); + ASSERT_TRUE(VirtualFileSystem::move("temp://dirA", "temp://dirB", false).hasValue()); + EXPECT_FALSE(VirtualFileSystem::exists("temp://dirA/nested/item.txt")); + EXPECT_TRUE(VirtualFileSystem::exists("temp://dirB/nested/item.txt")); + gp::String movedNested{}; + ASSERT_TRUE(VirtualFileSystem::readAllText("temp://dirB/nested/item.txt", movedNested).hasValue()); + EXPECT_EQ(movedNested.view(), gp::StringView("nested_payload")); + + // VfsError::toString constexpr check + static_assert(toString(VfsError::SandboxEscapeViolation) == "SandboxEscapeViolation"); + static_assert(toString(VfsError::ReadOnlyMount) == "ReadOnlyMount"); + EXPECT_EQ(toString(VfsError::CrossMountOperation), gp::StringView("CrossMountOperation")); + + // Verify unmountScheme clears all mounts for a scheme + EXPECT_EQ(VirtualFileSystem::unmountScheme("game://"), 2u); + EXPECT_FALSE(VirtualFileSystem::isSchemeMounted("game://")); + EXPECT_TRUE(VirtualFileSystem::unmountBackend("temp://", &tempMem)); +} + +TEST_F(VirtualFileSystemTest, EnumerateMountsDeterministicOrderAndConsoleDiagnostics) +{ + static_assert(toString(MountPriority::Base) == "Base"); + static_assert(toString(MountPriority::ModOverride) == "ModOverride"); + static_assert(toString(MountPriority::DeveloperOverride) == "DeveloperOverride"); + static_assert(toString(MountAccess::ReadOnly) == "ReadOnly"); + static_assert(toString(MountAccess::ReadWrite) == "ReadWrite"); + + // Empty VFS diagnostics before mounting anything + gp::console::IConsoleManager& consoleMgr = gp::console::IConsoleManager::get(); + gp::String captured{}; + gp::console::ConsoleOutputDelegate captureOut = gp::console::ConsoleOutputDelegate::createLambda( + [&captured](const gp::StringView line) noexcept -> void + { + captured.append(line); + captured.pushBack('\n'); + } + ); + + ASSERT_EQ(consoleMgr.processUserConsoleInput("vfs.Mounts", &captureOut), gp::console::ConsoleResult::Success); + EXPECT_TRUE(captured.view().contains("none registered")); + + // Mount physical and memory layers in scrambled priority order to verify deterministic sorting. + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_baseGameDir.view(), MountPriority::Base, MountAccess::ReadOnly).hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("user://", m_userSaveDir.view(), MountPriority::Base, MountAccess::ReadWrite) + .hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_modDir.view(), MountPriority::ModOverride, MountAccess::ReadOnly) + .hasValue() + ); + ASSERT_TRUE( + VirtualFileSystem::mount("game://", m_patchDir.view(), MountPriority::Patch, MountAccess::ReadOnly).hasValue() + ); + + // Seed files for vfs.Resolve, vfs.Exists, vfs.Stat, and vfs.Ls + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_baseGameDir.view(), "config.ini").view(), "base=1" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_modDir.view(), "config.ini").view(), "mod=2222" + ) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::createDirectoryTree(gp::platform::Paths::combine(m_patchDir.view(), "sub").view()) + .hasValue() + ); + ASSERT_TRUE( + gp::platform::FileSystem::writeAllText( + gp::platform::Paths::combine(m_patchDir.view(), "sub/patch.dat").view(), "patch_bytes" + ) + .hasValue() + ); + ASSERT_TRUE(VirtualFileSystem::writeAllText("user://save.bin", "12345").hasValue()); + + // enumerateMounts sorts by scheme ascending, then priority descending + MountPriority gamePrios[4]{}; + gp::USize gameCount = 0u; + const gp::USize visitedGame = VirtualFileSystem::enumerateMounts( + "game://", + [&gamePrios, &gameCount](const MountPointDesc& desc) noexcept -> bool + { + if (gameCount < 4u) + { + gamePrios[gameCount] = desc.priority; + } + ++gameCount; + return true; + } + ); + EXPECT_EQ(visitedGame, 3u); + ASSERT_EQ(gameCount, 3u); + EXPECT_EQ(gamePrios[0], MountPriority::ModOverride); + EXPECT_EQ(gamePrios[1], MountPriority::Patch); + EXPECT_EQ(gamePrios[2], MountPriority::Base); + + // Early stop terminates traversal immediately + const gp::USize stoppedCount = VirtualFileSystem::enumerateMounts( + "", + [](const MountPointDesc&) noexcept -> bool + { + return false; + } + ); + EXPECT_EQ(stoppedCount, 1u); + + // vfs.Status + captured.clear(); + ASSERT_EQ(consoleMgr.processUserConsoleInput("vfs.Status", &captureOut), gp::console::ConsoleResult::Success); + EXPECT_TRUE(captured.view().contains("total=4/32")); + EXPECT_TRUE(captured.view().contains("game=3")); + EXPECT_TRUE(captured.view().contains("user=1")); + + // vfs.Mounts (all & filtered & unmounted) + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Mounts game://", &captureOut), gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("ModOverride(400)")); + EXPECT_TRUE(captured.view().contains("Patch(300)")); + EXPECT_TRUE(captured.view().contains("Base(100)")); + EXPECT_FALSE(captured.view().contains("user://")); + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Mounts unknown://", &captureOut), gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("no mounts registered")); + + // vfs.Resolve (read-only, writable, sandbox escape, missing arg) + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Resolve game://config.ini", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("Canonical: game://config.ini")); + EXPECT_TRUE(captured.view().contains("ReadPath :")); + EXPECT_TRUE(captured.view().contains("WritePath: ")); + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Resolve user://save.bin", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("WritePath:")); + EXPECT_FALSE(captured.view().contains("")); + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Resolve game://../../etc/passwd", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("SandboxEscapeViolation")); + + captured.clear(); + ASSERT_EQ(consoleMgr.processUserConsoleInput("vfs.Resolve", &captureOut), gp::console::ConsoleResult::Success); + EXPECT_TRUE(captured.view().contains("Usage:")); + + // vfs.Exists + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Exists user://save.bin", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("exists=true")); + EXPECT_TRUE(captured.view().contains("isFile=true")); + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Exists unknown://missing.bin", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("SchemeNotMounted")); + + // vfs.Stat + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Stat game://config.ini", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("type=File")); + EXPECT_TRUE(captured.view().contains("size=8B")); // ModOverride ("mod=2222") wins over Base ("base=1") + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Stat game://does_not_exist.bin", &captureOut), + gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("NotFound")); + + // vfs.Ls (shallow and recursive) + captured.clear(); + ASSERT_EQ(consoleMgr.processUserConsoleInput("vfs.Ls game://", &captureOut), gp::console::ConsoleResult::Success); + EXPECT_TRUE(captured.view().contains("game://config.ini")); + EXPECT_TRUE(captured.view().contains("prio=ModOverride")); + EXPECT_TRUE(captured.view().contains("[DIR ]")); + EXPECT_FALSE(captured.view().contains("patch.dat")); + + captured.clear(); + ASSERT_EQ( + consoleMgr.processUserConsoleInput("vfs.Ls game:// -r", &captureOut), gp::console::ConsoleResult::Success + ); + EXPECT_TRUE(captured.view().contains("game://sub/patch.dat")); + EXPECT_TRUE(captured.view().contains("prio=Patch")); +} + +} // namespace gp::vfs::tests