Implement M5.7 local world publication and recovery

This commit is contained in:
dingo
2026-09-26 19:26:30 -04:00
parent 207f9e6953
commit 56f533c738
13 changed files with 874 additions and 14 deletions
+7 -1
View File
@@ -34,7 +34,7 @@ target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in
target_compile_features(evo_simulation PUBLIC cxx_std_23)
evo_owned_target(evo_simulation)
set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp)
set(evo_world_sources src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp src/world/edits.cpp src/world/codec.cpp src/world/local_files.cpp)
add_library(evo_world STATIC ${evo_world_sources})
add_library(evo::world ALIAS evo_world)
target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
@@ -84,6 +84,12 @@ if(BUILD_TESTING)
add_test(NAME world-codec-contracts COMMAND evo-world-codec-tests)
set_tests_properties(world-codec-contracts PROPERTIES TIMEOUT 120)
add_executable(evo-world-local-files-tests tests/world_local_files_tests.cpp)
target_link_libraries(evo-world-local-files-tests PRIVATE evo::world)
evo_owned_target(evo-world-local-files-tests)
add_test(NAME world-local-files-contracts COMMAND evo-world-local-files-tests)
set_tests_properties(world-local-files-contracts PROPERTIES TIMEOUT 120)
add_executable(evo-world-edit-tests tests/world_edit_tests.cpp)
target_link_libraries(evo-world-edit-tests PRIVATE evo::world)
evo_owned_target(evo-world-edit-tests)
+1
View File
@@ -17,6 +17,7 @@ network service. Dev verification manifests are separate from the simulation.
- [Actionable milestones 0–4 and later gates](docs/ROADMAP.md)
- [Open design questions](docs/architecture/OPEN_QUESTIONS.md)
- [World snapshots and edit journals](docs/world/WORLD_CODEC.md)
- [Local file publication manifest](schemas/local-world-manifest.md)
- [Transactional terrain excavation](docs/world/TERRAIN_EDITS.md)
- [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md)
- [Versioned abiotic base generation](docs/world/BASE_GENERATION.md)
+5 -1
View File
@@ -268,7 +268,11 @@ and dirty eviction refusal. M5.5 now implements [atomic excavation](world/TERRAI
with per-material volume conservation under [ADR-0046](adr/0046-transactional-excavation.md).
M5.6 is complete under [ADR-0047](adr/0047-world-codec.md):
[canonical snapshots and edit journals](world/WORLD_CODEC.md) validate geometry, debris
and retry state together. Next is 5.7: local publication, compaction and recovery.
and retry state together. M5.7 implements [single-writer local publication](adr/0048-local-publication.md):
two alternating manifest slots, immutable snapshot/journal payloads, verified detached
recovery, journal replay, checkpoint compaction and injected pre/post-commit interruption.
This is not a production multi-host durability or ownership service. M5.8 remains the
end-to-end deep-edit/restart and cost-evidence gate.
**Decisions still open:** final spherical layout, region dimensions, adaptive LOD,
field quantization beyond the initial experiment, hydrology and surface extraction.
+16 -4
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 47 ADRs.
diagrams, biological contracts, engineering constitution and 48 ADRs.
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M5.7 local publication and compaction | Verified snapshot/journal replacement, recovery and injected filesystem failures |
| 1 | M5.8 bounded world proof | Deep edit -> checkpoint compaction -> restart with same state/inventory and measured operation costs |
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
@@ -582,5 +582,17 @@ obligations. No mass conversion or durable acknowledgement is claimed. Next: M5.
Added bounded canonical world snapshot v1 and edit journal v1, world/frame and base
version checks, full geometry/debris/retry restore, semantic validation and detached
all-or-nothing replay. [Codec contract](world/WORLD_CODEC.md) and schemas define
memory/trust limits. Dirty flags remain set; no file publication or durable ACK is
implemented. Next: M5.7 local publication, compaction and recovery.
memory/trust limits. The M5.6 codec alone does not publish files or issue durable
acknowledgements. M5.7 local publication and recovery are implemented above.
## M5.7 local publication and recovery
ADR-0048 adds a single-writer local-filesystem adapter over the M5.6 codec. It uses
immutable checksum-named snapshot/journal blobs and two alternating canonical
manifest slots; replacing the inactive manifest is the publication point. Checkpoints
compact a committed journal only after a caller supplies the recovered/advanced
state. Recovery validates the selected snapshot and complete journal replay into a
detached ChunkStore. Tests cover lock exclusion, journal/restart, compaction, failpoints
before and after publication, malformed manifests and missing published payloads.
FNV remains a corruption detector, and this local adapter makes no host-loss,
multi-region or production durability claim. Filesystem orphan cleanup is deferred.
+65
View File
@@ -0,0 +1,65 @@
# ADR-0048: Local snapshot and journal publication
## Status
Accepted for M5.7 single-process development files. Not the M7 production durable store.
## Context
M5.6 provides canonical bounded buffers. Bytes become current only after a recoverable
manifest points to verified payloads. A previous committed snapshot must survive while
a replacement is prepared and published.
## Decision
Use a trusted host-supplied root, then derive a directory from hex world/frame IDs.
Hold an exclusive OS lock for one writer. Payloads use immutable content-addressed
names containing the M5.6 FNV checksum; always compare complete bytes if a name exists.
No object is overwritten. Write a same-directory temporary with exclusive/truncated
access, flush file contents, atomically link/rename to its final payload name, then
flush the directory.
Maintain two fixed manifest slots. A manifest carries magic/version/length, identity,
monotonic generation, snapshot checksum/covered command, optional journal checksum and
end command, and checksum. Write/flush a temporary manifest and atomically replace only
the inactive slot; flush parent directory. That replacement is the local commit point.
Never alter the active manifest or source payload before that point. If a failure is
ambiguous after publication, poison this handle and require reopen/recovery. A valid
manifest referencing missing/corrupt data fails closed; do not roll back acknowledged
state silently. No automatic orphan deletion in this gate.
Snapshot checkpoint validates bytes by restoring them under budget before publication.
A journal commit must match the current checkpoint's exact bytes and high-water, and
pass detached replay. Only one journal segment is active per checkpoint; checkpoint
after replay to compact it. Recovery validates the selected manifest and referenced
payloads using M5.6, then replays the optional segment before returning a candidate.
Existing valid manifest stays the source until new publication completes.
Implement the minimal native OS boundary directly: POSIX lock/write/fsync/link/rename/
directory fsync; Windows exclusive CreateFile and write-through replacement. No third
party library. Root directory is trusted and locally administered. Files are not
network-safe/authenticated; FNV detects accidental corruption only.
Provide one-shot failure injection at payload sync, manifest sync, and manifest publish
for deterministic crash-boundary tests. After injected interruption, discard the handle
and reopen. A failure before manifest replacement yields old state; after replacement
yields new state. Allocation/OS errors do not clear dirty state.
## Alternatives Considered
In-place overwrite can destroy the old checkpoint on short write. A single manifest can
be torn. Renaming the active file to a backup creates a missing-pointer crash interval.
SQLite/database/object-store dependencies are future infrastructure, not a local gate.
## Benefits
Clear commit point, old-source retention, bounded recovery scan and injected boundary tests.
## Costs
Two manifests and immutable payloads; orphan accumulation and no concurrent writers.
POSIX/Windows code paths need platform review and Linux CI.
## Risks
Filesystem/controller hardware may violate flush guarantees. Windows/POSIX/network filesystems
differ. Same-host files do not survive host loss. Fail-closed corruption may require
operator recovery. No production DR/RPO claim.
## Consequences
Test first checkpoint, journal, compaction, restart continuation, competing lock, corrupt
payload/manifest, every injected boundary, missing sequence and full-disk/OS errors.
Record Linux checks separately. M5.8 performs the whole create/edit/compact/restart proof.
+2
View File
@@ -53,3 +53,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0046: Transactional excavation](0046-transactional-excavation.md) - accepted for M5.5 atomic local volume transfers and bounded exact-request replay.
- [ADR-0047: World codecs](0047-world-codec.md) - accepted for M5.6 bounded canonical snapshots and detached edit-journal replay.
- [ADR-0048: Local publication](0048-local-publication.md) - accepted for M5.7 single-writer snapshot/journal publication and recovery.
+14 -2
View File
@@ -143,10 +143,22 @@ verified durable failure domain containing the complete causal recovery chain
and referenced payloads before acknowledgment; restoring an older backup cannot silently undo
permadeath. That admission/DR requirement is a World0 launch gate.
## Implemented M5.7 local file publication boundary
[ADR-0048](../adr/0048-local-publication.md) and
[the manifest schema](../../schemas/local-world-manifest.md) implement a single-writer
development file backend over the M5.6 codecs. Immutable checksum-named payloads
are installed before alternating manifests; atomic replacement of the inactive
manifest is the commit point. Recovery validates the selected snapshot and replays
its optional one-segment journal into a detached store. Pre-publication failures
retain the previous generation; a post-publication interruption requires reopen
and recovers the new one. Orphan files are retained. This is not the M7 fenced,
multi-worker or host-loss durability contract above.
## Implemented M5.6 local world codec boundary
[ADR-0047](../adr/0047-world-codec.md) and [the codec contract](../world/WORLD_CODEC.md)
implement bounded canonical buffers carrying world/frame IDs, base versions, covered
command high-water, resident cells, debris and exact retry state. Detached replay
verifies predecessor and final state. This is in-memory codec validation, not the
production durability contract above. File publication/crash recovery is M5.7.
verifies predecessor and final state. This remains an in-memory codec beneath
M5.7's local file publication adapter.
+36 -5
View File
@@ -1,10 +1,41 @@
# Validation report
Recorded 2026-09-19. Latest verified Linux delivery: **run 1402 passed** on
`4c2cc04ac47d37c6191a9ef02d4bbba716a930dc`. Native checks apply to base commit `8ab48d3` plus the
foundation-delivery working changes committed with this report. Simulation rules
and snapshot format remain version 1; the only C++ change is benchmark metadata.
Results below distinguish executed checks from pending Linux/cluster gates.
Recorded 2026-09-19; subsequent gate evidence is appended by date below. Latest
historical verified Linux delivery at the time of the foundation report was **run
1402** on `4c2cc04ac47d37c6191a9ef02d4bbba716a930dc`. Native check history and later
gate-specific results are kept separate. Results distinguish executed checks from
pending Linux/cluster gates.
## M5.7 local publication - 2026-09-26
Added the single-writer local filesystem adapter and manifest v1 under ADR-0048.
The implementation is in `include/evo/world/local_files.hpp` and
`src/world/local_files.cpp`; `schemas/local-world-manifest.md` defines the durable
bytes. The commit point is replacement of the inactive manifest slot after the
referenced payload has been written, flushed, installed and directory-flushed.
Recovery validates the snapshot and optional journal before returning a new store.
FNV is only a corruption check; this is not host-loss durability or the M7 region
ownership system.
Executed on Windows x64 / MSVC 19.44.35207:
- `tools/windows-check.ps1 -Preset release -Action check`: configure/build passed;
47/47 CTests passed with `NDEBUG`.
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 and
warnings-as-errors build passed; 47/47 CTests passed.
- `tools/windows-check.ps1 -Preset asan -Action check`: build passed; 47/47 CTests
passed. The Windows preset is not Linux ASan+UBSan evidence.
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
- `git diff --check`: passed before commit.
New coverage validates checkpoint/journal/recovery, compaction over a published
journal, exclusive writer lock, all three injected publication boundaries, corrupt
manifest and missing published payload failure. Before-manifest failures recover
the previous generation; after-manifest replacement recovers the new generation.
Actual power-cut/full-disk behavior, POSIX syscall path, Linux CI/libFuzzer, and
filesystem-controller flush guarantees remain unverified locally. There is no
automatic orphan cleanup, production storage adapter, Kubernetes deployment or
World0 change.
## Tools and host
+6 -1
View File
@@ -77,6 +77,11 @@ insufficient memory. A 128-input deterministic fuzz smoke is in CTest; Linux CI
validation instead of stopping only at the envelope. Local Windows smoke is not a
claim that Linux coverage-guided fuzzing has executed.
Next M5.7: publish/compact local files with verified replacement and failure injection.
M5.7 adds a separate local publication contract in [ADR-0048](../adr/0048-local-publication.md)
and [the manifest schema](../../schemas/local-world-manifest.md). Two alternating
manifest slots select immutable M5.6 snapshot/journal payloads. Recovery validates
the selected snapshot and optional journal into a detached store. The manifest
replacement is the local commit point; this provides no multi-host durability,
production lease, authentication or disaster recovery guarantee.
M5.6 does not write files, fsync, delete journals, clear dirty state or recover a live
server process. M7 supplies the production durability/ownership path.
+78
View File
@@ -0,0 +1,78 @@
#pragma once
#include "evo/world/chunks.hpp"
#include <cstdint>
#include <expected>
#include <filesystem>
#include <memory>
#include <optional>
#include <span>
namespace evo::world {
enum class LocalFileError : std::uint8_t {
invalid_identity,
busy,
empty,
corrupt_manifest,
corrupt_payload,
identity_mismatch,
invalid_snapshot,
invalid_journal,
stale_checkpoint,
journal_already_published,
generation_exhausted,
io,
interrupted,
poisoned
};
enum class PublicationInterruption : std::uint8_t {
none,
after_payload_sync,
after_manifest_sync,
after_manifest_publish
};
struct FileCommit {
std::uint64_t generation{}, covered_command{}, snapshot_checksum{};
bool has_journal{};
auto operator<=>(const FileCommit&) const = default;
};
class LocalWorldFiles {
public:
[[nodiscard]] static std::expected<std::unique_ptr<LocalWorldFiles>, LocalFileError>
open(const std::filesystem::path& trusted_root, WorldIdentity identity, std::size_t byte_budget,
PublicationInterruption interrupt_once = PublicationInterruption::none);
LocalWorldFiles(const LocalWorldFiles&) = delete;
LocalWorldFiles& operator=(const LocalWorldFiles&) = delete;
LocalWorldFiles(LocalWorldFiles&&) = delete;
LocalWorldFiles& operator=(LocalWorldFiles&&) = delete;
~LocalWorldFiles();
[[nodiscard]] std::expected<std::unique_ptr<ChunkStore>, LocalFileError> recover() const;
[[nodiscard]] std::expected<FileCommit, LocalFileError> checkpoint(const ChunkStore& store);
[[nodiscard]] std::expected<FileCommit, LocalFileError>
publish_journal(std::span<const std::uint8_t> checkpoint,
std::span<const std::uint8_t> journal);
[[nodiscard]] std::optional<FileCommit> current() const noexcept;
private:
struct Lock;
struct Manifest {
std::uint64_t generation{}, snapshot_checksum{}, covered_command{};
std::uint64_t journal_checksum{}, journal_end{};
bool has_journal{};
};
LocalWorldFiles(std::filesystem::path directory, WorldIdentity identity, std::size_t budget,
PublicationInterruption interruption, std::unique_ptr<Lock> lock);
[[nodiscard]] std::expected<FileCommit, LocalFileError>
publish(std::span<const std::uint8_t> payload, bool journal, std::uint64_t covered,
std::uint64_t payload_checksum);
std::filesystem::path directory_;
WorldIdentity identity_;
std::size_t budget_;
PublicationInterruption interruption_;
std::unique_ptr<Lock> lock_;
std::optional<Manifest> manifest_;
std::size_t active_slot_{};
std::uint64_t generation_high_water_{};
bool poisoned_{};
};
} // namespace evo::world
+53
View File
@@ -0,0 +1,53 @@
# Local world manifest v1
This is an M5.7 single-host publication record, not a production/world-server
manifest. The encoding is fixed-width little-endian and exactly 88 bytes:
| Offset | Width | Field |
|---:|---:|---|
| 0 | 8 | magic `0x0031464d574f5645` |
| 8 | 4 | version `1` |
| 12 | 4 | total length `88` |
| 16 | 8 | world identity |
| 24 | 8 | frame identity |
| 32 | 8 | generation, nonzero |
| 40 | 8 | FNV-1a checksum of complete snapshot payload |
| 48 | 8 | snapshot command high-water |
| 56 | 1 | journal-present flag, 0 or 1 |
| 57 | 7 | reserved zero bytes |
| 64 | 8 | FNV-1a checksum of complete journal payload, or zero |
| 72 | 8 | journal final command, or zero |
| 80 | 8 | FNV-1a checksum of bytes 0 through 79 |
FNV detects accidental corruption only. It is not authentication. Payload names
are derived from their checksum and complete bytes are compared when a name
already exists. A manifest reference is accepted only after the M5.6 snapshot
restore and optional all-or-nothing journal replay succeed.
## Publication and recovery
The writer holds the per-world OS lock. It writes a same-directory temporary
payload and flushes it, installs a new immutable payload name, then flushes the
directory. It writes and flushes the inactive manifest temporary and atomically
replaces that manifest slot. The replacement is the commit point. Slots alternate
by generation. Recovery parses both slots and selects the greatest generation;
any malformed present slot or invalid selected payload fails closed. It never
silently falls back from a valid published pointer to an older generation.
```mermaid
stateDiagram-v2
[*] --> PreparePayload
PreparePayload --> PayloadSynced
PayloadSynced --> PayloadInstalled
PayloadInstalled --> PrepareInactiveManifest
PrepareInactiveManifest --> ManifestSynced
ManifestSynced --> Published: atomic replace (commit)
ManifestSynced --> PreviousGeneration: failure before replace
Published --> ReopenRequired: ambiguous/post-publication error
Published --> Recoverable: durable slot + referenced payload
```
An interruption before replacement recovers the old generation. An interruption
after replacement recovers the new generation. Unknown files and orphan payloads
are ignored; this version does not delete them. OS locks, fsync/write-through and
same-directory rename semantics depend on the local filesystem and storage stack.
+420
View File
@@ -0,0 +1,420 @@
#include "evo/world/local_files.hpp"
#include <algorithm>
#include <array>
#include <fstream>
#include <iomanip>
#include <ranges>
#include <sstream>
#include <string>
#include <system_error>
#ifdef _WIN32
#define NOMINMAX
#include <windows.h>
#else
#include <cerrno>
#include <fcntl.h>
#include <sys/file.h>
#include <sys/stat.h>
#include <unistd.h>
#endif
namespace evo::world {
namespace {
constexpr std::uint64_t manifest_magic = 0x31464d574f5645ULL;
constexpr std::uint32_t manifest_version = 1;
constexpr std::size_t manifest_size = 88;
std::uint64_t hash(std::span<const std::uint8_t> bytes) noexcept {
std::uint64_t value = 14695981039346656037ULL;
for (const auto byte : bytes) {
value = (value ^ byte) * 1099511628211ULL;
}
return value;
}
void put(WorldBytes& out, std::uint64_t value, unsigned width) {
for (unsigned i = 0; i < width; ++i) {
out.push_back(static_cast<std::uint8_t>(value & 0xffU));
value >>= 8U;
}
}
std::uint64_t get(std::span<const std::uint8_t> in, std::size_t offset, unsigned width) {
std::uint64_t value{};
for (unsigned i = 0; i < width; ++i) {
value |= static_cast<std::uint64_t>(in[offset + i]) << (i * 8U);
}
return value;
}
std::string hex(std::uint64_t value) {
std::ostringstream stream;
stream << std::hex << std::setfill('0') << std::setw(16) << value;
return stream.str();
}
template <typename Manifest> WorldBytes encode_manifest(WorldIdentity id, const Manifest& m) {
WorldBytes b;
b.reserve(manifest_size);
put(b, manifest_magic, 8);
put(b, manifest_version, 4);
put(b, manifest_size, 4);
put(b, id.world, 8);
put(b, id.frame, 8);
put(b, m.generation, 8);
put(b, m.snapshot_checksum, 8);
put(b, m.covered_command, 8);
put(b, m.has_journal ? 1 : 0, 1);
for (int i = 0; i < 7; ++i)
put(b, 0, 1);
put(b, m.journal_checksum, 8);
put(b, m.journal_end, 8);
put(b, hash(b), 8);
return b;
}
template <typename Manifest>
std::expected<Manifest, LocalFileError> decode_manifest(std::span<const std::uint8_t> b,
WorldIdentity id) {
if (b.size() != manifest_size || get(b, 0, 8) != manifest_magic ||
get(b, 8, 4) != manifest_version || get(b, 12, 4) != manifest_size || get(b, 56, 1) > 1 ||
get(b, 80, 8) != hash(b.first(80))) {
return std::unexpected(LocalFileError::corrupt_manifest);
}
for (std::size_t i = 57; i < 64; ++i) {
if (b[i] != 0)
return std::unexpected(LocalFileError::corrupt_manifest);
}
if (get(b, 16, 8) != id.world || get(b, 24, 8) != id.frame)
return std::unexpected(LocalFileError::identity_mismatch);
Manifest m{get(b, 32, 8), get(b, 40, 8), get(b, 48, 8),
get(b, 64, 8), get(b, 72, 8), get(b, 56, 1) != 0};
if (!m.generation || (!m.has_journal && (m.journal_checksum || m.journal_end)) ||
(m.has_journal && !m.journal_checksum))
return std::unexpected(LocalFileError::corrupt_manifest);
return m;
}
std::expected<WorldBytes, LocalFileError> read_file(const std::filesystem::path& path,
std::size_t max) {
std::error_code ec;
if (!std::filesystem::exists(path, ec)) {
if (!ec)
return std::unexpected(LocalFileError::empty);
return std::unexpected(LocalFileError::io);
}
std::ifstream stream(path, std::ios::binary);
if (!stream)
return std::unexpected(LocalFileError::io);
stream.seekg(0, std::ios::end);
const auto end = stream.tellg();
if (end < 0 || static_cast<std::uintmax_t>(end) > max)
return std::unexpected(LocalFileError::io);
WorldBytes bytes(static_cast<std::size_t>(end));
stream.seekg(0, std::ios::beg);
if (!bytes.empty() && !stream.read(reinterpret_cast<char*>(bytes.data()),
static_cast<std::streamsize>(bytes.size())))
return std::unexpected(LocalFileError::io);
return bytes;
}
bool sync_directory(const std::filesystem::path& path) {
#ifdef _WIN32
(void)path;
return true; // Payload/manifest replacement uses MOVEFILE_WRITE_THROUGH.
#else
const int fd = ::open(path.c_str(), O_RDONLY | O_DIRECTORY);
if (fd < 0)
return false;
const bool ok = ::fsync(fd) == 0;
::close(fd);
return ok;
#endif
}
bool write_synced(const std::filesystem::path& path, std::span<const std::uint8_t> bytes) {
#ifdef _WIN32
HANDLE file = CreateFileW(path.c_str(), GENERIC_WRITE, 0, nullptr, CREATE_ALWAYS,
FILE_ATTRIBUTE_NORMAL | FILE_FLAG_WRITE_THROUGH, nullptr);
if (file == INVALID_HANDLE_VALUE)
return false;
std::size_t offset = 0;
bool ok = true;
while (offset < bytes.size()) {
const auto amount =
static_cast<DWORD>(std::min<std::size_t>(bytes.size() - offset, 1U << 20U));
DWORD wrote{};
if (!WriteFile(file, bytes.data() + offset, amount, &wrote, nullptr) || !wrote) {
ok = false;
break;
}
offset += wrote;
}
ok = FlushFileBuffers(file) != 0 && ok;
CloseHandle(file);
return ok;
#else
const int fd = ::open(path.c_str(), O_WRONLY | O_CREAT | O_TRUNC, 0600);
if (fd < 0)
return false;
std::size_t offset = 0;
bool ok = true;
while (offset < bytes.size()) {
const auto wrote = ::write(fd, bytes.data() + offset, bytes.size() - offset);
if (wrote < 0 && errno == EINTR)
continue;
if (wrote <= 0) {
ok = false;
break;
}
offset += static_cast<std::size_t>(wrote);
}
ok = ::fsync(fd) == 0 && ok;
::close(fd);
return ok;
#endif
}
bool install_immutable(const std::filesystem::path& temp, const std::filesystem::path& dest) {
#ifdef _WIN32
return MoveFileExW(temp.c_str(), dest.c_str(), MOVEFILE_WRITE_THROUGH) != 0;
#else
if (::link(temp.c_str(), dest.c_str()) != 0)
return false;
return ::unlink(temp.c_str()) == 0;
#endif
}
bool replace_file(const std::filesystem::path& temp, const std::filesystem::path& dest) {
#ifdef _WIN32
return MoveFileExW(temp.c_str(), dest.c_str(),
MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH) != 0;
#else
return ::rename(temp.c_str(), dest.c_str()) == 0;
#endif
}
} // namespace
struct LocalWorldFiles::Lock {
#ifdef _WIN32
HANDLE handle{INVALID_HANDLE_VALUE};
~Lock() {
if (handle != INVALID_HANDLE_VALUE)
CloseHandle(handle);
}
#else
int fd{-1};
~Lock() {
if (fd >= 0) {
::flock(fd, LOCK_UN);
::close(fd);
}
}
#endif
};
LocalWorldFiles::LocalWorldFiles(std::filesystem::path directory, WorldIdentity identity,
std::size_t budget, PublicationInterruption interruption,
std::unique_ptr<Lock> lock)
: directory_{std::move(directory)}, identity_{identity}, budget_{budget},
interruption_{interruption}, lock_{std::move(lock)} {}
LocalWorldFiles::~LocalWorldFiles() = default;
std::expected<std::unique_ptr<LocalWorldFiles>, LocalFileError>
LocalWorldFiles::open(const std::filesystem::path& root, WorldIdentity identity, std::size_t budget,
PublicationInterruption interruption) {
if (!identity.world || !identity.frame || !budget)
return std::unexpected(LocalFileError::invalid_identity);
const auto directory = root / ("world-" + hex(identity.world) + "-" + hex(identity.frame));
std::error_code ec;
std::filesystem::create_directories(directory, ec);
if (ec || !std::filesystem::is_directory(directory, ec) || ec)
return std::unexpected(LocalFileError::io);
auto lock = std::make_unique<Lock>();
#ifdef _WIN32
lock->handle = CreateFileW((directory / L".lock").c_str(), GENERIC_READ | GENERIC_WRITE, 0,
nullptr, OPEN_ALWAYS, FILE_ATTRIBUTE_HIDDEN, nullptr);
if (lock->handle == INVALID_HANDLE_VALUE)
return std::unexpected(LocalFileError::busy);
#else
lock->fd = ::open((directory / ".lock").c_str(), O_CREAT | O_RDWR, 0600);
if (lock->fd < 0 || ::flock(lock->fd, LOCK_EX | LOCK_NB) != 0)
return std::unexpected(LocalFileError::busy);
#endif
auto result = std::unique_ptr<LocalWorldFiles>(
new LocalWorldFiles(directory, identity, budget, interruption, std::move(lock)));
for (std::size_t slot = 0; slot < 2; ++slot) {
auto bytes = read_file(directory / ("manifest." + std::to_string(slot)), manifest_size);
if (!bytes) {
if (bytes.error() == LocalFileError::empty)
continue;
return std::unexpected(LocalFileError::io);
}
auto parsed = decode_manifest<Manifest>(*bytes, identity);
if (!parsed)
return std::unexpected(parsed.error());
if (parsed->generation > result->manifest_.value_or(Manifest{}).generation) {
result->manifest_ = *parsed;
result->active_slot_ = slot;
}
result->generation_high_water_ =
std::max(result->generation_high_water_, parsed->generation);
}
return result;
}
std::optional<FileCommit> LocalWorldFiles::current() const noexcept {
if (!manifest_)
return std::nullopt;
return FileCommit{manifest_->generation, manifest_->covered_command,
manifest_->snapshot_checksum, manifest_->has_journal};
}
std::expected<std::unique_ptr<ChunkStore>, LocalFileError> LocalWorldFiles::recover() const {
if (!manifest_)
return std::unexpected(LocalFileError::empty);
const auto snapshot_path =
directory_ / ("snapshot-" + hex(manifest_->snapshot_checksum) + ".bin");
auto bytes = read_file(snapshot_path, max_world_snapshot_bytes);
if (!bytes || hash(*bytes) != manifest_->snapshot_checksum)
return std::unexpected(LocalFileError::corrupt_payload);
const auto covered = bytes->size() >= 80 ? get(*bytes, 72, 8) : 0;
if (covered != manifest_->covered_command)
return std::unexpected(LocalFileError::corrupt_manifest);
auto base = ChunkStore::restore(*bytes, identity_, budget_);
if (!base)
return std::unexpected(LocalFileError::invalid_snapshot);
if (!manifest_->has_journal)
return std::move(*base);
auto journal = read_file(directory_ / ("journal-" + hex(manifest_->journal_checksum) + ".bin"),
max_world_journal_bytes);
if (!journal || hash(*journal) != manifest_->journal_checksum)
return std::unexpected(LocalFileError::corrupt_payload);
auto replayed = replay_edit_journal(*bytes, *journal, identity_, budget_);
if (!replayed)
return std::unexpected(LocalFileError::invalid_journal);
const auto final = (**replayed).snapshot(identity_);
if (!final || final->size() < 80 || get(*final, 72, 8) != manifest_->journal_end)
return std::unexpected(LocalFileError::invalid_journal);
return std::move(*replayed);
}
std::expected<FileCommit, LocalFileError>
LocalWorldFiles::publish(std::span<const std::uint8_t> payload, bool journal, std::uint64_t covered,
std::uint64_t payload_checksum) {
if (poisoned_)
return std::unexpected(LocalFileError::poisoned);
if (generation_high_water_ == UINT64_MAX)
return std::unexpected(LocalFileError::generation_exhausted);
const auto prefix = journal ? "journal-" : "snapshot-";
const auto payload_path = directory_ / (prefix + hex(payload_checksum) + ".bin");
std::error_code ec;
if (std::filesystem::exists(payload_path, ec)) {
auto existing =
read_file(payload_path, journal ? max_world_journal_bytes : max_world_snapshot_bytes);
if (!existing || !std::ranges::equal(*existing, payload))
return std::unexpected(LocalFileError::corrupt_payload);
} else {
const auto temp = directory_ / (std::string{prefix} + ".payload.tmp");
std::filesystem::remove(temp, ec);
ec.clear();
if (!write_synced(temp, payload))
return std::unexpected(LocalFileError::io);
if (interruption_ == PublicationInterruption::after_payload_sync) {
interruption_ = PublicationInterruption::none;
poisoned_ = true;
return std::unexpected(LocalFileError::interrupted);
}
if (!install_immutable(temp, payload_path) || !sync_directory(directory_))
return std::unexpected(LocalFileError::io);
}
if (interruption_ == PublicationInterruption::after_payload_sync) {
interruption_ = PublicationInterruption::none;
poisoned_ = true;
return std::unexpected(LocalFileError::interrupted);
}
Manifest candidate{};
candidate.generation = generation_high_water_ + 1;
if (journal) {
if (!manifest_)
return std::unexpected(LocalFileError::empty);
candidate = *manifest_;
candidate.generation = generation_high_water_ + 1;
candidate.has_journal = true;
candidate.journal_checksum = payload_checksum;
candidate.journal_end = covered;
} else {
candidate.snapshot_checksum = payload_checksum;
candidate.covered_command = covered;
}
const auto inactive = manifest_ ? 1U - active_slot_ : 0U;
const auto temp_manifest = directory_ / ("manifest." + std::to_string(inactive) + ".tmp");
const auto dest_manifest = directory_ / ("manifest." + std::to_string(inactive));
const auto encoded = encode_manifest(identity_, candidate);
std::filesystem::remove(temp_manifest, ec);
ec.clear();
if (!write_synced(temp_manifest, encoded))
return std::unexpected(LocalFileError::io);
if (interruption_ == PublicationInterruption::after_manifest_sync) {
interruption_ = PublicationInterruption::none;
poisoned_ = true;
return std::unexpected(LocalFileError::interrupted);
}
if (!replace_file(temp_manifest, dest_manifest))
return std::unexpected(LocalFileError::io);
if (!sync_directory(directory_)) {
poisoned_ = true;
return std::unexpected(LocalFileError::io);
}
manifest_ = candidate;
active_slot_ = inactive;
generation_high_water_ = candidate.generation;
if (interruption_ == PublicationInterruption::after_manifest_publish) {
interruption_ = PublicationInterruption::none;
poisoned_ = true;
return std::unexpected(LocalFileError::interrupted);
}
return FileCommit{candidate.generation, candidate.covered_command, candidate.snapshot_checksum,
candidate.has_journal};
}
std::expected<FileCommit, LocalFileError> LocalWorldFiles::checkpoint(const ChunkStore& store) {
if (poisoned_)
return std::unexpected(LocalFileError::poisoned);
auto bytes = store.snapshot(identity_);
if (!bytes)
return std::unexpected(LocalFileError::invalid_snapshot);
auto valid = ChunkStore::restore(*bytes, identity_, budget_);
if (!valid || bytes->size() < 80)
return std::unexpected(LocalFileError::invalid_snapshot);
const auto covered = get(*bytes, 72, 8);
const auto required =
manifest_ ? (manifest_->has_journal ? manifest_->journal_end : manifest_->covered_command)
: 0;
if (covered < required)
return std::unexpected(LocalFileError::stale_checkpoint);
return publish(*bytes, false, covered, hash(*bytes));
}
std::expected<FileCommit, LocalFileError>
LocalWorldFiles::publish_journal(std::span<const std::uint8_t> checkpoint,
std::span<const std::uint8_t> journal) {
if (poisoned_)
return std::unexpected(LocalFileError::poisoned);
if (!manifest_)
return std::unexpected(LocalFileError::empty);
if (manifest_->has_journal)
return std::unexpected(LocalFileError::journal_already_published);
auto base = read_file(directory_ / ("snapshot-" + hex(manifest_->snapshot_checksum) + ".bin"),
max_world_snapshot_bytes);
if (!base || !std::ranges::equal(*base, checkpoint) ||
hash(checkpoint) != manifest_->snapshot_checksum)
return std::unexpected(LocalFileError::stale_checkpoint);
auto replayed = replay_edit_journal(checkpoint, journal, identity_, budget_);
if (!replayed)
return std::unexpected(LocalFileError::invalid_journal);
const auto final = (**replayed).snapshot(identity_);
if (!final || final->size() < 80)
return std::unexpected(LocalFileError::invalid_journal);
const auto end = get(*final, 72, 8);
if (end < manifest_->covered_command)
return std::unexpected(LocalFileError::invalid_journal);
return publish(journal, true, end, hash(journal));
}
} // namespace evo::world
+171
View File
@@ -0,0 +1,171 @@
#include "evo/world/local_files.hpp"
#include <array>
#include <chrono>
#include <filesystem>
#include <fstream>
#include <source_location>
#include <stdexcept>
#include <string>
namespace {
using namespace evo::world;
constexpr WorldIdentity identity{71, 91};
constexpr std::size_t budget = 2'000'000;
void check(bool ok, std::source_location at = std::source_location::current()) {
if (!ok)
throw std::runtime_error("local world files line " + std::to_string(at.line()));
}
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
struct TempRoot {
std::filesystem::path path =
std::filesystem::temp_directory_path() /
("evo-local-files-" +
std::to_string(std::chrono::steady_clock::now().time_since_epoch().count()));
TempRoot() {
std::filesystem::create_directories(path);
}
~TempRoot() {
std::error_code ignored;
std::filesystem::remove_all(path, ignored);
}
};
std::unique_ptr<ChunkStore> make_store() {
auto result =
ChunkStore::create({}, 4, budget, {{VolumeUnits{1'000'000}, VolumeUnits{1'000'000}}});
CHECK(result);
CHECK((*result)->load({0, 0, -2}));
return std::move(*result);
}
std::filesystem::path world_dir(const std::filesystem::path& root) {
return root / "world-0000000000000047-000000000000005b";
}
void checkpoint_and_journal_round_trip() {
TempRoot root;
auto files = LocalWorldFiles::open(root.path, identity, budget);
CHECK(files && !(*files)->recover() && (*files)->recover().error() == LocalFileError::empty);
auto original = make_store();
auto checkpoint = original->snapshot(identity);
CHECK(checkpoint);
auto committed = (*files)->checkpoint(*original);
CHECK(committed && committed->generation == 1 && !committed->has_journal);
const auto view = original->view({0, 0, -2});
CHECK(view);
const std::array<CellCut, 1> cuts{{{{0, 0, -2}, {0, 0, 0}, view->revision(), 2}}};
ExcavationRequest request{1, 1, cuts, 0};
const auto digest = excavation_digest(request);
CHECK(digest);
request.digest = *digest;
const std::array<ExcavationRequest, 1> requests{request};
auto journal = make_edit_journal(*checkpoint, identity, requests, budget);
CHECK(journal);
auto journal_commit = (*files)->publish_journal(*checkpoint, *journal);
CHECK(journal_commit && journal_commit->generation == 2 && journal_commit->has_journal);
CHECK(!(*files)->publish_journal(*checkpoint, *journal));
const auto stale_checkpoint = (*files)->checkpoint(*original);
CHECK(!stale_checkpoint && stale_checkpoint.error() == LocalFileError::stale_checkpoint);
auto recovered = (*files)->recover();
CHECK(recovered);
auto expected = replay_edit_journal(*checkpoint, *journal, identity, budget);
CHECK(expected);
CHECK((*recovered)->snapshot(identity) == (**expected).snapshot(identity));
(*files).reset();
auto reopened = LocalWorldFiles::open(root.path, identity, budget);
CHECK(reopened);
const auto reopened_commit = (*reopened)->current();
CHECK(reopened_commit.has_value());
CHECK(reopened_commit.value_or(FileCommit{}).generation == 2);
CHECK((*reopened)->recover());
auto compacted = (*reopened)->checkpoint(**recovered);
CHECK(compacted && compacted->generation == 3 && !compacted->has_journal);
CHECK((*reopened)->recover());
}
void interruptions_preserve_commit_point() {
for (const auto point :
{PublicationInterruption::after_payload_sync, PublicationInterruption::after_manifest_sync,
PublicationInterruption::after_manifest_publish}) {
TempRoot root;
{
auto files = LocalWorldFiles::open(root.path, identity, budget);
CHECK(files);
auto initial = make_store();
CHECK((*files)->checkpoint(*initial));
}
auto interrupted = LocalWorldFiles::open(root.path, identity, budget, point);
CHECK(interrupted);
auto changed = make_store();
const auto result = (*interrupted)->checkpoint(*changed);
CHECK(!result && result.error() == LocalFileError::interrupted);
CHECK(!(*interrupted)->checkpoint(*changed));
(*interrupted).reset();
auto recovered = LocalWorldFiles::open(root.path, identity, budget);
CHECK(recovered);
const auto commit = (*recovered)->current();
CHECK(commit.has_value());
const auto generation = commit.value_or(FileCommit{}).generation;
CHECK(generation == (point == PublicationInterruption::after_manifest_publish ? 2 : 1));
CHECK((*recovered)->recover());
}
}
void lock_and_corruption_fail_closed() {
TempRoot root;
auto first = LocalWorldFiles::open(root.path, identity, budget);
CHECK(first);
auto busy = LocalWorldFiles::open(root.path, identity, budget);
CHECK(!busy && busy.error() == LocalFileError::busy);
auto state = make_store();
CHECK((*first)->checkpoint(*state));
(*first).reset();
auto reopened = LocalWorldFiles::open(root.path, identity, budget);
CHECK(reopened && (*reopened)->recover());
const auto manifest = world_dir(root.path) / "manifest.0";
{
std::fstream file(manifest, std::ios::binary | std::ios::in | std::ios::out);
CHECK(file);
file.seekp(40);
const char corrupt = '\x7f';
file.write(&corrupt, 1);
}
(*reopened).reset();
auto corrupt = LocalWorldFiles::open(root.path, identity, budget);
CHECK(!corrupt && corrupt.error() == LocalFileError::corrupt_manifest);
}
void missing_published_payload_fails_closed() {
TempRoot root;
std::uint64_t checksum{};
{
auto files = LocalWorldFiles::open(root.path, identity, budget);
CHECK(files);
auto state = make_store();
auto published = (*files)->checkpoint(*state);
CHECK(published);
checksum = published->snapshot_checksum;
}
const auto payload = world_dir(root.path) / ("snapshot-" + [&] {
constexpr char digits[] = "0123456789abcdef";
std::string value(16, '0');
for (int i = 15; i >= 0; --i) {
value[static_cast<std::size_t>(i)] = digits[checksum & 15U];
checksum >>= 4U;
}
return value;
}() + ".bin");
std::error_code ec;
CHECK(std::filesystem::remove(payload, ec) && !ec);
auto files = LocalWorldFiles::open(root.path, identity, budget);
CHECK(files);
const auto recovered = (*files)->recover();
CHECK(!recovered && recovered.error() == LocalFileError::corrupt_payload);
}
} // namespace
int main() try {
checkpoint_and_journal_round_trip();
interruptions_preserve_commit_point();
lock_and_corruption_fail_closed();
missing_published_payload_fails_closed();
} catch (const std::exception&) {
return 1;
}