Confirm beacon file moves before acknowledging publication

This commit is contained in:
mikecarper committed 2026-10-16 10:32:27 -07:00
1 parent e69c89e8d3
commit 22c31c0246
4 files changed
+434 -9

No files matched your search

+36 -7
View File
@@ -185,6 +185,23 @@ bool openWrite(FILESYSTEM* fs, const char* path, File& file) {
#endif
return bool(file);
}
enum class FileMove : uint8_t { Moved, Unchanged, Unknown };
__attribute__((noinline)) FileMove moveFile(FILESYSTEM* fs, const char* from, const char* to) {
fs->rename(from, to);
bool source = false, destination = false;
if (!filePresence(fs, from, source) || !filePresence(fs, to, destination))
return FileMove::Unknown;
// This confirms the namespace move of the prevalidated image, not a fresh
// public-byte readback. Pico's boolean metadata API cannot expose IO errors.
if (!source && destination) return FileMove::Moved;
if (source && !destination) return FileMove::Unchanged;
return FileMove::Unknown;
}
bool removeFile(FILESYSTEM* fs, const char* path) {
fs->remove(path);
bool present = false;
return filePresence(fs, path, present) && !present;
}
} // namespace
BeaconManager::~BeaconManager() { delete[] slots_; }
@@ -263,16 +280,24 @@ bool BeaconManager::commit(const char* path, const char* backup,
bool active_backed_up = false;
if (!filePresence(fs_, path, active_present) || !filePresence(fs_, backup, backup_present)) return false;
if (active_present) {
if (backup_present && !fs_->remove(backup)) return false;
if (!fs_->rename(path, backup)) return false;
if (backup_present && !removeFile(fs_, backup)) return false;
const FileMove moved = moveFile(fs_, path, backup);
if (moved != FileMove::Moved) {
if (moved == FileMove::Unknown) hold = true;
return false;
}
active_backed_up = true;
backup_present = true;
}
if (!fs_->rename(temporary, path)) {
const FileMove published = moveFile(fs_, temporary, path);
if (published != FileMove::Moved) {
// A candidate may already be public. Preserve every surviving name and
// never let a replacing rename roll an old image over uncertain new data.
if (published == FileMove::Unknown) { hold = true; return false; }
// A pre-existing backup can be older than an already transmitted ID.
// Roll back only the active image moved by this transaction; promoting
// an unrelated backup could make that ID reusable after the next boot.
if (active_backed_up && !fs_->rename(backup, path)) hold = true;
if (active_backed_up && moveFile(fs_, backup, path) != FileMove::Moved) hold = true;
return false;
}
// A leftover backup after a successful commit is harmless. Never choose it
@@ -304,7 +329,10 @@ bool BeaconManager::saveConfig(unsigned changed_slot, const BeaconSlot* changed,
uint8_t verified_hours = 0; bool verified_initialized = false;
if (!ok || readConfig(ConfigTemp, nullptr, verified_hours, verified_initialized) != ReadResult::Valid
|| verified_hours != hours || verified_initialized != initialized) return false;
return commit(ConfigPath, ConfigBackup, ConfigTemp, hold_);
const bool saved = commit(ConfigPath, ConfigBackup, ConfigTemp, hold_);
// A held manager must not leave an already-admitted old beacon running.
if (hold_ && mesh_) mesh_->cancelBeaconRadioFrame();
return saved;
}
bool BeaconManager::saveIds(uint32_t last) {
@@ -360,8 +388,9 @@ void BeaconManager::begin(FILESYSTEM* fs, Mesh* mesh, RTCClock* rtc, const char*
else if (result != ReadResult::Valid) {
const ReadResult backup = readConfig(ConfigBackup, nullptr, hours, initialized);
if (backup == ReadResult::Valid) {
if ((fs_->exists(ConfigPath) && !fs_->remove(ConfigPath))
|| !fs_->rename(ConfigBackup, ConfigPath)) hold_ = true;
bool present = false;
if (!filePresence(fs_, ConfigPath, present) || (present && !removeFile(fs_, ConfigPath))
|| moveFile(fs_, ConfigBackup, ConfigPath) != FileMove::Moved) hold_ = true;
result = ReadResult::Valid;
} else if (result != ReadResult::Missing || backup != ReadResult::Missing) hold_ = true;
}
@@ -0,0 +1,51 @@
#pragma once
// Extend the existing in-memory file adapter only for beacon namespace faults.
// File remains bound to the same base object and uses the real read/write API.
#define MemoryFS BeaconBaseFS
#include "../../../radio_profiles/mocks/helpers/IdentityStore.h"
#undef MemoryFS
#include <array>
#include <cassert>
enum { LFS_ERR_NOENT = -2, LFS_ERR_IO = -5 };
struct lfs_info {};
class MemoryFS : public BeaconBaseFS {
public:
enum Fault { None, Reject, Noop, LateError, Metadata, BothNames, NeitherName };
std::array<Fault, 8> faults{};
unsigned renames = 0, metadata_probes = 0, fail_metadata_probe = 0;
unsigned error_probe = 1;
bool metadata_error = false;
void _lockFS() {}
void _unlockFS() {}
MemoryFS* _getFS() { return this; }
bool rename(const char* from, const char* to) {
assert(++renames < faults.size());
const Fault fault = faults[renames];
if (fault == Reject) return false;
if (fault == Noop) return true;
if (fault == BothNames || fault == NeitherName) {
assert(exists(from) && !exists(to));
if (fault == BothNames) files[to] = files.at(from);
else files.erase(from);
return true;
}
const bool moved = BeaconBaseFS::rename(from, to);
if (fault == Metadata) {
assert(moved);
fail_metadata_probe = metadata_probes + error_probe;
}
return fault == LateError ? false : moved;
}
void clearFaults() {
faults.fill(None); renames = 0; fail_rename = 0;
fail_metadata_probe = 0; metadata_error = false;
}
};
inline int lfs_stat(MemoryFS* fs, const char* path, lfs_info*) {
++fs->metadata_probes;
if (fs->metadata_error || fs->metadata_probes == fs->fail_metadata_probe)
return LFS_ERR_IO;
return fs->exists(path) ? 0 : LFS_ERR_NOENT;
}
+257
View File
@@ -0,0 +1,257 @@
#include <helpers/BeaconConfig.h>
#include <helpers/IdentityStore.h>
#define private public
#include <helpers/BeaconManager.h>
#undef private
#include <Mesh.h>
#include <cassert>
#include <cstdio>
#include <cstring>
#include <initializer_list>
#include <string>
uint64_t beacon_test_time = 0;
constexpr uint64_t H = mesh::BeaconManager::HourMillis;
using Fault = MemoryFS::Fault;
struct Fixture {
MemoryFS fs;
mesh::Mesh mesh;
mesh::RTCClock clock;
mesh::BeaconManager manager;
char name[16] = "Namespace";
char reply[256] = {};
uint64_t now = 0;
explicit Fixture(bool replacing) {
fs.rename_replaces = replacing;
g_mock_millis = 0; beacon_test_time = 0;
manager.begin(&fs, &mesh, &clock, name);
}
void cmd(const char* command, bool success) {
assert(manager.handle(command, reply, sizeof(reply)));
assert((std::strncmp(reply, "Err", 3) != 0) == success);
}
void mc(const char* text) {
const std::string command = std::string("set beacon 1 meshcore 906.5,62.5,7,5,14 ") + text;
cmd(command.c_str(), true);
}
void mt() { cmd("set beacon 1 meshtext US LongFast 14 MT", true); }
void tick(uint64_t delta) {
now += delta; beacon_test_time = now; g_mock_millis += uint32_t(delta);
manager.loop(g_mock_millis);
}
void reboot() {
fs.clearFaults();
manager.begin(&fs, &mesh, &clock, name);
}
void oldRam(bool existing) {
assert(!existing ? (!manager.slots_ || !manager.slots_[0].enabled)
: manager.slots_ && !std::strcmp(manager.slots_[0].text, "Old"));
}
};
const char* const SetNew = "set beacon 1 meshcore 907.5,125,8,6,10 New";
void healthy() {
for (bool replacing : {false, true}) {
Fixture f(replacing); f.mc("Old"); f.cmd(SetNew, true); f.reboot();
f.cmd("get beacon 1", true); assert(std::strstr(f.reply, "New"));
f.mt(); f.tick(2 * H); assert(f.mesh.sends.size() == 1);
}
}
void assertHeld(Fixture& f, bool existing) {
assert(f.manager.hold_);
f.oldRam(existing);
assert(!f.mesh.pending);
const auto files = f.fs.files;
const auto renames = f.fs.renames;
const auto attempts = f.mesh.attempts;
f.cmd("get beacon 1", false);
f.cmd(SetNew, false);
f.tick(48 * H);
assert(f.fs.files == files && f.fs.renames == renames && f.mesh.attempts == attempts);
}
void config() {
for (bool replacing : {false, true}) for (bool existing : {false, true}) {
Fixture expected(replacing); expected.cmd(SetNew, true);
const auto next = expected.fs.files.at("/beacons");
for (Fault fault : {MemoryFS::None, MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError}) {
Fixture f(replacing);
if (existing) f.mc("Old");
const auto old = f.fs.files;
f.fs.clearFaults(); f.fs.faults[existing ? 2 : 1] = fault;
const bool committed = fault == MemoryFS::None || fault == MemoryFS::LateError;
f.cmd(SetNew, committed);
assert(!f.manager.hold_);
if (committed) {
assert(f.fs.files.at("/beacons") == next);
assert(!f.fs.exists("/beacons.tmp") && !f.fs.exists("/beacons.bak"));
} else {
f.oldRam(existing);
if (existing) assert(f.fs.files.at("/beacons") == old.at("/beacons"));
else assert(!f.fs.exists("/beacons"));
}
f.reboot(); f.cmd("get beacon 1", true);
assert(std::strstr(f.reply, committed ? "New" : existing ? "Old" : "off"));
if (!committed) { f.cmd(SetNew, true); assert(f.fs.files.at("/beacons") == next); }
}
}
// Both backup and publication moves are checked, not only the final rename.
for (bool replacing : {false, true}) for (Fault fault : {MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError}) {
Fixture f(replacing); f.mc("Old");
const auto old = f.fs.files.at("/beacons");
f.fs.clearFaults(); f.fs.faults[1] = fault;
f.cmd(SetNew, fault == MemoryFS::LateError);
assert(!f.manager.hold_);
if (fault != MemoryFS::LateError) {
assert(f.fs.renames == 1 && f.fs.files.at("/beacons") == old);
f.oldRam(true); f.cmd(SetNew, true);
}
}
for (bool replacing : {false, true}) {
Fixture f(replacing); f.mc("Old");
const auto old = f.fs.files.at("/beacons");
f.fs.files["/beacons.bak"] = old;
f.fs.clearFaults(); f.fs.fail_remove = true;
f.cmd(SetNew, false);
assert(!f.manager.hold_ && !f.fs.renames);
assert(f.fs.files.at("/beacons") == old && f.fs.files.at("/beacons.bak") == old);
f.oldRam(true); f.fs.fail_remove = false; f.cmd(SetNew, true);
}
}
void uncertainty() {
for (bool replacing : {false, true}) for (bool existing : {false, true}) {
for (unsigned stage : {1U, 2U}) {
if (!existing && stage != 1) continue;
for (Fault fault : {MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
for (unsigned probe : {1U, 2U}) {
Fixture f(replacing); if (existing) { f.mc("Old"); f.tick(2 * H); }
const auto old = f.fs.files;
f.fs.clearFaults(); f.fs.faults[stage] = fault; f.fs.error_probe = probe;
f.cmd(SetNew, false);
assert(f.fs.renames == stage); // No speculative rollback or cleanup.
assert(f.fs.exists("/beacons.tmp") || stage == (existing ? 2U : 1U));
if (existing && stage == 2) assert(f.fs.files.at("/beacons.bak") == old.at("/beacons"));
assertHeld(f, existing);
if (fault == MemoryFS::Metadata) {
f.reboot(); f.cmd("get beacon 1", true);
assert(std::strstr(f.reply, existing && stage == 1 ? "Old" : "New"));
}
}
}
}
}
}
void rollback() {
for (bool replacing : {false, true}) {
for (Fault fault : {MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError,
MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
Fixture f(replacing); f.mc("Old"); f.tick(2 * H);
const auto old = f.fs.files.at("/beacons");
f.fs.clearFaults(); f.fs.faults[2] = MemoryFS::Reject; f.fs.faults[3] = fault;
f.cmd(SetNew, false); assert(f.fs.renames == 3);
if (fault == MemoryFS::LateError) {
assert(!f.manager.hold_ && f.mesh.pending);
assert(f.fs.files.at("/beacons") == old);
f.oldRam(true); f.cmd(SetNew, true);
} else {
assert(f.fs.exists("/beacons.tmp"));
if (fault != MemoryFS::Metadata && fault != MemoryFS::NeitherName)
assert(f.fs.files.at("/beacons.bak") == old);
assertHeld(f, true);
}
}
}
}
void recovery() {
for (bool replacing : {false, true}) for (bool corrupt_active : {false, true}) {
for (Fault fault : {MemoryFS::None, MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError,
MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
Fixture f(replacing); f.mc("Old");
const auto old = f.fs.files.at("/beacons");
f.fs.files["/beacons.bak"] = old; f.fs.files.erase("/beacons");
if (corrupt_active) { f.fs.files["/beacons"] = old; f.fs.files["/beacons"][40] ^= 1; }
f.fs.clearFaults(); f.fs.faults[1] = fault;
f.manager.begin(&f.fs, &f.mesh, &f.clock, f.name);
const bool recovered = fault == MemoryFS::None || fault == MemoryFS::LateError;
f.cmd("get beacon 1", recovered);
if (recovered) assert(std::strstr(f.reply, "Old") && f.fs.files.at("/beacons") == old);
else {
assert(f.manager.hold_ && f.fs.renames == 1);
if (fault != MemoryFS::Metadata && fault != MemoryFS::NeitherName)
assert(f.fs.files.at("/beacons.bak") == old);
}
}
}
}
void ids() {
for (bool replacing : {false, true}) {
for (unsigned stage : {1U, 2U}) for (Fault fault : {MemoryFS::None, MemoryFS::Reject, MemoryFS::Noop,
MemoryFS::LateError, MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
Fixture f(replacing); f.mt();
const auto last = f.manager.last_id_;
f.fs.clearFaults(); f.fs.faults[stage] = fault;
f.tick(2 * H);
const bool committed = fault == MemoryFS::None || fault == MemoryFS::LateError;
assert(f.mesh.sends.size() == unsigned(committed));
if (committed) {
assert(!f.manager.ids_hold_ && f.manager.last_id_ == last + 1);
assert(f.mesh.sends.back().id == last + 1);
} else {
assert(f.manager.ids_hold_ && f.manager.last_id_ == last);
const auto files = f.fs.files;
f.tick(24 * H); assert(f.mesh.sends.empty() && f.fs.files == files);
// A held ID store does not quarantine independent MeshCore beacons.
f.cmd("set beacon 2 meshcore 906.5,62.5,7,5,14 MC", true);
assert(!f.manager.hold_);
}
if (committed || fault == MemoryFS::Reject || fault == MemoryFS::Noop
|| (fault == MemoryFS::Metadata && stage == 2)) {
f.reboot();
const auto count = f.mesh.sends.size(); f.tick(2 * H);
assert(f.mesh.sends.size() == count + 1);
assert(f.mesh.sends.back().id == last + (committed || (fault == MemoryFS::Metadata && stage == 2) ? 2 : 1));
}
}
// Initial ID reservation has no public predecessor or rollback target.
for (Fault fault : {MemoryFS::None, MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError,
MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
Fixture f(replacing); f.fs.clearFaults(); f.fs.faults[1] = fault;
const bool committed = fault == MemoryFS::None || fault == MemoryFS::LateError;
f.cmd("set beacon 1 meshtext US LongFast 14 MT", committed);
assert(f.manager.ids_hold_ != committed);
f.tick(2 * H); assert(f.mesh.sends.size() == unsigned(committed));
}
for (Fault fault : {MemoryFS::Reject, MemoryFS::Noop, MemoryFS::LateError,
MemoryFS::Metadata, MemoryFS::BothNames, MemoryFS::NeitherName}) {
Fixture f(replacing); f.mt();
const auto last = f.manager.last_id_;
const auto old = f.fs.files.at("/beacon_ids");
f.fs.clearFaults(); f.fs.faults[2] = MemoryFS::Reject; f.fs.faults[3] = fault;
f.tick(2 * H);
assert(f.mesh.sends.empty() && f.manager.ids_hold_ && f.manager.last_id_ == last);
assert(f.fs.renames == 3 && f.fs.exists("/beacon_ids.tmp"));
if (fault == MemoryFS::Reject || fault == MemoryFS::Noop || fault == MemoryFS::BothNames)
assert(f.fs.files.at("/beacon_ids.bak") == old);
if (fault == MemoryFS::LateError || fault == MemoryFS::Metadata)
assert(f.fs.files.at("/beacon_ids") == old);
const auto files = f.fs.files;
f.tick(24 * H); assert(f.mesh.sends.empty() && f.fs.files == files);
f.reboot();
const bool public_restored = fault == MemoryFS::LateError || fault == MemoryFS::Metadata
|| fault == MemoryFS::BothNames;
assert(f.manager.ids_hold_ != public_restored);
f.tick(2 * H);
assert(f.mesh.sends.size() == unsigned(public_restored));
if (public_restored) assert(f.mesh.sends.back().id == last + 1);
}
}
}
int main(int argc, char** argv) {
assert(argc == 2);
if (!std::strcmp(argv[1], "healthy")) healthy();
else if (!std::strcmp(argv[1], "config")) config();
else if (!std::strcmp(argv[1], "uncertainty")) uncertainty();
else if (!std::strcmp(argv[1], "rollback")) rollback();
else if (!std::strcmp(argv[1], "recovery")) recovery();
else if (!std::strcmp(argv[1], "ids")) ids();
else assert(false);
std::printf("PASS: actual beacon namespace %s\n", argv[1]);
}
+90 -2
View File
@@ -9,6 +9,7 @@ import subprocess
import sys
import tempfile
import unittest
from cpp_source import body
ROOT = Path(__file__).resolve().parents[1]
@@ -105,12 +106,99 @@ class BeaconManagerTest(unittest.TestCase):
def test_negative_control_live_counter_backup_rewind_is_detected(self):
source = (ROOT / "src/helpers/BeaconManager.cpp").read_text(encoding="ascii")
guard = "if (active_backed_up && !fs_->rename(backup, path))"
guard = "if (active_backed_up && moveFile(fs_, backup, path) != FileMove::Moved)"
self.assertEqual(source.count(guard), 1)
self.negative_control("live_rewound", source.replace(
guard, "if ((active_backed_up || backup_present) && !fs_->rename(backup, path))"),
guard, "if ((active_backed_up || backup_present) && moveFile(fs_, backup, path) != FileMove::Moved)"),
"live_backup")
class BeaconNamespaceTest(unittest.TestCase):
@classmethod
def setUpClass(cls):
compiler = shutil.which("g++") or shutil.which("clang++")
if not compiler:
raise AssertionError("a C++ compiler is required")
cls.work = tempfile.TemporaryDirectory(prefix="meshcore-beacon-namespace-")
cls.addClassCleanup(cls.work.cleanup)
cls.exe = Path(cls.work.name) / "namespace"
# nRF's real filePresence path exposes metadata errors. Both replacing
# (LittleFS/Pico) and nonreplacing (SPIFFS) rename models run in C++.
cls.command = [compiler, "-std=c++17", "-Wall", "-Wextra", "-Werror", "-O1", "-g",
*(["-fsanitize=address,undefined", "-fno-sanitize-recover=all", "-fno-pie", "-no-pie"]
if sys.platform.startswith("linux") else []),
"-DNRF52_PLATFORM=1", "-DMESH_ENABLE_TX_BEACONS=1",
"-DMESH_ENABLE_MESHTEXT_CHAT=1", "-DMESH_ENABLE_MESHTEXT_WIRE=1",
"-I", str(ROOT / "test/fixtures/beacons/namespace_mocks"),
"-I", str(ROOT / "test/fixtures/beacons/mocks"),
"-I", str(ROOT / "test/fixtures/radio_profiles/mocks"),
"-isystem", str(ROOT / "test/mocks"), "-I", str(ROOT / "src"),
"-I", str(ROOT / "src/helpers"),
str(ROOT / "src/helpers/BeaconManager.cpp"),
str(ROOT / "src/helpers/MeshtextChat.cpp"),
str(ROOT / "test/fixtures/beacons/namespace_test.cpp"), "-o", str(cls.exe)]
result = subprocess.run(cls.command, capture_output=True, text=True, timeout=60)
if result.returncode:
raise AssertionError(result.stdout + result.stderr)
def run_scenario(self, scenario, executable=None):
result = subprocess.run([str(executable or self.exe), scenario], capture_output=True,
text=True, timeout=30)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
def test_healthy_publications_and_id_reservations(self):
self.run_scenario("healthy")
def test_config_acknowledgement_follows_observed_publication(self):
self.run_scenario("config")
def test_uncertain_moves_preserve_authorities_and_cancel_admitted_old_frame(self):
self.run_scenario("uncertainty")
def test_rollback_does_not_overwrite_an_uncertain_candidate(self):
self.run_scenario("rollback")
def test_startup_backup_recovery_confirms_namespace_moves(self):
self.run_scenario("recovery")
def test_meshtext_ids_are_reserved_only_after_observed_publication(self):
self.run_scenario("ids")
def test_rename_return_only_negative_control_is_detected(self):
source = (ROOT / "src/helpers/BeaconManager.cpp").read_text(encoding="ascii")
original = body(source, "bool BeaconManager::commit(")
old = r'''bool BeaconManager::commit(const char* path, const char* backup,
const char* temporary, bool& hold) {
bool active_present = false, backup_present = false;
bool active_backed_up = false;
if (!filePresence(fs_, path, active_present) || !filePresence(fs_, backup, backup_present)) return false;
if (active_present) {
if (backup_present && !fs_->remove(backup)) return false;
if (!fs_->rename(path, backup)) return false;
active_backed_up = true;
backup_present = true;
}
if (!fs_->rename(temporary, path)) {
if (active_backed_up && !fs_->rename(backup, path)) hold = true;
return false;
}
if (backup_present) fs_->remove(backup);
return true;
}'''
self.assertNotEqual(original, old)
generated = Path(self.work.name) / "rename_return_only.cpp"
generated.write_text(source.replace(original, old), encoding="ascii")
executable = Path(self.work.name) / "rename_return_only"
command = list(self.command)
command[command.index(str(ROOT / "src/helpers/BeaconManager.cpp"))] = str(generated)
command[-1] = str(executable)
result = subprocess.run(command, capture_output=True, text=True, timeout=60)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.run_scenario("healthy", executable)
result = subprocess.run([str(executable), "config"], capture_output=True, text=True, timeout=30)
self.assertNotEqual(result.returncode, 0, "rename-return-only behavior escaped the matrix")
self.assertIn("Assertion", result.stderr)
if __name__ == "__main__":
unittest.main()