Fence Companion channel writes after uncertain publication

Latch only channel storage on Indeterminate writer outcomes, including failed transaction setup. Preserve ordinary failure retries, confirmed rollback, contacts and the live accepted channel keys.

Exercise actual CLI and binary callers with all four storage backends, reboot behavior and exact missing-latch negative controls. Share TX storage failure diagnostics to retain the strict Wio-E5 Mini flash gate.

Verified 103 related host tests, four platform firmware qualifications and linked nRF52 crypto/stack checks. A separate stale-backup constructor/no-op acknowledgement case remains under audit.
This commit is contained in:
mikecarper committed 2026-10-16 11:22:36 -07:00
1 parent 508dd23673
commit 24b1264a0e
6 files changed
+370 -3

No files matched your search

+1
View File
@@ -322,6 +322,7 @@ jobs:
run: |
python3 -B test/test_companion_channel_alias.py -v
python3 -B test/test_companion_tx_routing.py -v
python3 -B test/test_companion_channel_publication.py -v
python3 -B test/test_companion_traffic_routing.py -v
python3 -B test/test_ethernet_kiss.py -v
python3 -B test/test_ethernet_radio.py -v
+5
View File
@@ -3379,6 +3379,11 @@ bool DataStore::saveChannels(DataStoreHost* host) {
file.close();
#endif
}
#if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM) || defined(ESP32_PLATFORM) || defined(RP2040_PLATFORM)
// Failed publication can leave disk newer than the caller's rolled-back RAM.
if (file.outcome() == decltype(file)::Outcome::Indeterminate)
_channel_load_incomplete = true;
#endif
return success;
}
+2 -2
View File
@@ -3698,7 +3698,7 @@ bool MyMesh::handleTxRoutingCommand(const char* command, char* reply, size_t rep
}
if (parsed.set && (!canMutateContacts()
|| (parsed.channel && _store->hasIncompleteChannelLoad()))) {
snprintf(reply, reply_size, "Error: storage unavailable");
snprintf(reply, reply_size, "Error: storage unavailable; TX routing not saved");
return true;
}
@@ -3768,7 +3768,7 @@ bool MyMesh::handleTxRoutingCommand(const char* command, char* reply, size_t rep
}
}
if (!saved) {
snprintf(reply, reply_size, "Error: TX routing was not saved");
snprintf(reply, reply_size, "Error: storage unavailable; TX routing not saved");
return true;
}
policy = parsed.policy;
+159
View File
@@ -0,0 +1,159 @@
static void seed(MyMesh& node) {
#if defined(STM32_PLATFORM) || defined(NRF52_PLATFORM)
node.store.fs.rename_replaces = true;
#endif
strcpy(node.channels[0].name, "Public");
strcpy(node.channels[1].name, "Other");
strcpy(node.contacts[1].name, "Healthy contact");
node.channels[0].channel.tx_radio = mesh::RADIO_TX_PRIMARY;
memset(node.channels[0].channel.secret, 0x11, 16);
assert(node.store.saveChannels(&node));
assert(last_channel_outcome == 2); // Actual writer: Committed.
}
static void failPublicObservationAfterPublish(MyMesh& node) {
#if defined(STM32_PLATFORM) || defined(NRF52_PLATFORM)
node.store.fs.arm_public_read_failure = true;
#else
node.store.fs.arm_namespace_failure = true;
#endif
}
static void publication_uncertainty_cannot_acknowledge_a_rolled_back_value() {
MyMesh node;
seed(node);
const auto old_image = node.store.fs.files.at("/channels2");
failPublicObservationAfterPublish(node);
char reply[160];
assert(node.handleTxRoutingCommand("set tx.channel 0 both", reply, sizeof(reply)));
assert(strstr(reply, "not saved") && last_channel_outcome == 3);
assert(node.channels[0].channel.tx_radio == mesh::RADIO_TX_PRIMARY);
const auto published = node.store.fs.files.at("/channels2");
assert(published != old_image);
assert(published[0] == mesh::encodeRadioTxPolicy(mesh::RADIO_TX_BOTH));
assert(!node.store.hasIncompleteContactLoad());
const unsigned writes = node.writes;
assert(node.handleTxRoutingCommand("set tx.channel 0 radio", reply, sizeof(reply)));
// Exact regression invariant: without the publication latch this same-value
// branch returns OK without saving, although a reboot restores BOTH.
assert(strstr(reply, "storage unavailable"));
assert(node.writes == writes && node.store.hasIncompleteChannelLoad());
assert(node.store.fs.files.at("/channels2") == published);
assert(!node.store.saveChannels(&node));
assert(node.handleTxRoutingCommand("set tx.user \"Healthy contact\" both", reply, sizeof(reply)));
assert(!strncmp(reply, "OK", 2)); // Contact authority is independent.
MyMesh reboot;
reboot.store.fs.files = node.store.fs.files;
reboot.store.loadChannels(&reboot);
assert(reboot.channels[0].channel.tx_radio == mesh::RADIO_TX_BOTH);
assert(!reboot.store.hasIncompleteChannelLoad());
}
static void prepublication_failures_remain_retryable() {
MyMesh node;
seed(node);
const auto old_image = node.store.fs.files.at("/channels2");
node.store.fs.fail_write = true;
char reply[160];
assert(node.handleTxRoutingCommand("set tx.channel 0 both", reply, sizeof(reply)));
assert(strstr(reply, "not saved") && last_channel_outcome == 1);
assert(node.store.fs.files.at("/channels2") == old_image);
assert(!node.store.hasIncompleteChannelLoad());
node.store.fs.fail_write = false;
const unsigned writes = node.writes;
assert(node.handleTxRoutingCommand("set tx.channel 0 radio", reply, sizeof(reply)));
assert(!strncmp(reply, "OK", 2) && node.writes == writes);
assert(node.store.fs.files.at("/channels2")[0] == mesh::encodeRadioTxPolicy(mesh::RADIO_TX_PRIMARY));
assert(node.handleTxRoutingCommand("set tx.channel 0 both", reply, sizeof(reply)));
assert(!strncmp(reply, "OK", 2) && last_channel_outcome == 2);
}
static void binary_psk_rollback_preserves_live_communications_but_blocks_writes() {
MyMesh node;
seed(node);
failPublicObservationAfterPublish(node);
uint8_t frame[2 + 32 + 16] = {};
frame[0] = CMD_SET_CHANNEL;
memcpy(frame + 2, "Public", 6);
memset(frame + 2 + 32, 0xAA, 16);
node.applyChannelFrame(frame, sizeof(frame));
assert(node.last_error == ERR_CODE_FILE_IO_ERROR && !node.binary_ack);
assert(last_channel_outcome == 3 && node.store.hasIncompleteChannelLoad());
assert(node.channels[0].channel.secret[0] == 0x11);
const auto published = node.store.fs.files.at("/channels2");
assert(published[36] == 0xAA);
ChannelDetails active;
assert(node.getChannel(0, active) && active.channel.secret[0] == 0x11);
memset(frame + 2 + 32, 0xBB, 16);
node.last_error = 0;
node.applyChannelFrame(frame, sizeof(frame));
assert(node.last_error == ERR_CODE_FILE_IO_ERROR && !node.binary_ack);
assert(node.channels[0].channel.secret[0] == 0x11);
assert(node.store.fs.files.at("/channels2") == published);
MyMesh reboot;
reboot.store.fs.files = node.store.fs.files;
reboot.store.loadChannels(&reboot);
assert(reboot.channels[0].channel.secret[0] == 0xAA);
}
#if defined(ESP32_PLATFORM) || defined(RP2040_PLATFORM)
static void known_rollback_is_retryable_but_failed_rollback_is_quarantined() {
for (bool rollback_fails : {false, true}) {
MyMesh node;
seed(node);
const auto old_image = node.store.fs.files.at("/channels2");
node.store.fs.fail_rename_from = {"/channels2.tmp"};
if (rollback_fails) node.store.fs.fail_rename_from.push_back("/channels2.bak");
char reply[160];
assert(node.handleTxRoutingCommand("set tx.channel 0 both", reply, sizeof(reply)));
assert(strstr(reply, "not saved"));
assert(last_channel_outcome == (rollback_fails ? 3 : 1));
assert(node.store.hasIncompleteChannelLoad() == rollback_fails);
assert(!node.store.hasIncompleteContactLoad());
node.store.fs.fail_rename_from.clear();
if (rollback_fails) {
assert(!node.store.fs.exists("/channels2"));
assert(node.store.fs.files.at("/channels2.bak") == old_image);
assert(node.handleTxRoutingCommand("set tx.channel 0 radio", reply, sizeof(reply)));
assert(strstr(reply, "storage unavailable"));
MyMesh reboot;
reboot.store.fs.files = node.store.fs.files;
reboot.store.loadChannels(&reboot);
assert(reboot.channels[0].channel.tx_radio == mesh::RADIO_TX_PRIMARY);
} else {
assert(node.store.fs.files.at("/channels2") == old_image);
assert(node.handleTxRoutingCommand("set tx.channel 0 radio", reply, sizeof(reply)));
assert(!strncmp(reply, "OK", 2));
assert(node.handleTxRoutingCommand("set tx.channel 0 both", reply, sizeof(reply)));
assert(!strncmp(reply, "OK", 2));
}
}
}
static void constructor_recovery_uncertainty_is_quarantined_without_a_commit() {
MyMesh node;
seed(node);
const auto old_image = node.store.fs.files.at("/channels2");
node.store.fs.files["/channels2.bak"] = old_image;
node.store.fs.files.erase("/channels2");
node.store.fs.arm_namespace_failure = true;
last_channel_outcome = -1;
assert(!node.store.saveChannels(&node));
assert(last_channel_outcome == 3 && node.store.hasIncompleteChannelLoad());
assert(!node.store.hasIncompleteContactLoad());
assert(node.store.fs.files.at("/channels2") == old_image);
assert(!node.store.fs.exists("/channels2.bak"));
assert(!node.store.fs.exists("/channels2.tmp"));
}
#endif
int main() {
prepublication_failures_remain_retryable();
publication_uncertainty_cannot_acknowledge_a_rolled_back_value();
binary_psk_rollback_preserves_live_communications_but_blocks_writes();
#if defined(ESP32_PLATFORM) || defined(RP2040_PLATFORM)
known_rollback_is_retryable_but_failed_rollback_is_quarantined();
constructor_recovery_uncertainty_is_quarantined_without_a_commit();
#endif
puts("PASS: channel publication authority");
}
+182
View File
@@ -0,0 +1,182 @@
#!/usr/bin/env python3
"""Verify real channel writers and callers preserve publication authority."""
from pathlib import Path
import subprocess
import tempfile
import unittest
import test_companion_tx_routing as tx
from test_radio_receive_contract import method
from test_companion_preferences_transaction import esp_recovery_helpers
ROOT = Path(__file__).resolve().parents[1]
def publication_fixture(work, missing_latch):
store = (ROOT / "examples/companion_radio/DataStore.cpp").read_text()
header = (ROOT / "examples/companion_radio/DataStore.h").read_text()
mesh = (ROOT / "examples/companion_radio/MyMesh.cpp").read_text()
backend = (ROOT / "test/fixtures/radio_profiles/mocks/helpers/IdentityStore.h").read_text()
backend = backend.replace(" bool fail_write = false;", """
bool arm_public_read_failure = false, arm_namespace_failure = false;
unsigned public_read_failures = 0;
mutable unsigned namespace_failures = 0;
bool fail_write = false;""", 1)
backend = backend.replace(" bool exists(const char* path) const { return files.count(path); }", """
bool exists(const char* path) const {
if (namespace_failures && !strcmp(path, "/channels2")) {
--namespace_failures;
return false; // Arduino-Pico hides an lfs_stat IO error as absence.
}
return files.count(path);
}""", 1)
backend = backend.replace(" files[to] = files[from]; files.erase(from); return true;", """
files[to] = files[from]; files.erase(from);
if (!strcmp(to, "/channels2")) {
if (arm_public_read_failure && !strcmp(from, "/channels2.tmp")) {
public_read_failures = 3;
arm_public_read_failure = false;
}
if (arm_namespace_failure) {
namespace_failures = 1;
arm_namespace_failure = false;
}
}
return true;""", 1)
backend = backend.replace(" if (*mode == 'r' && fail_read_open) return {};", """
if (*mode == 'r' && public_read_failures && !strcmp(path, "/channels2")) {
--public_read_failures;
return {};
}
if (*mode == 'r' && fail_read_open) return {};""", 1)
(work / "helpers").mkdir()
(work / "helpers/IdentityStore.h").write_text(backend)
transaction = (ROOT / "src/helpers/ContactFileTransaction.h").read_text()
(work / "ContactFileTransaction.h").write_text(transaction.replace(
'#include "IdentityStore.h"', '#include <helpers/IdentityStore.h>'))
save = method(store, "bool DataStore::saveChannels(")
latch = (" if (file.outcome() == decltype(file)::Outcome::Indeterminate)\n"
" _channel_load_incomplete = true;\n")
if missing_latch:
# Restore precisely the pre-fix missing publication-authority latch.
assert save.count(latch) == 1
save = save.replace(latch, "")
# Observability only: record the real writer result, including a failed
# constructor which never entered the if(file) or commit() branches.
assert save.count(" return success;") == 1
save = save.replace(" return success;", " last_channel_outcome = int(file.outcome());\n return success;")
recovery = esp_recovery_helpers(store)
recovery = recovery.replace(" assert(!strncmp(path, \"/spiffs\", 7));", """
assert(!strncmp(path, "/spiffs", 7));
if (fs->namespace_failures && !strcmp(path + 7, "/channels2")) {
--fs->namespace_failures;
errno = EIO;
return -1; // ESP metadata errors remain distinguishable from absence.
}""", 1)
methods = recovery + "\n" + method(mesh, "bool MyMesh::handleTxRoutingCommand(")
methods += "\n" + method(store, "void DataStore::loadChannels(")
methods += "\n" + save + "\n" + method(store, "bool DataStore::hasIncompleteContactLoad(")
binary_start = mesh.index(" } else if (cmd_frame[0] == CMD_SET_CHANNEL && len >= 2 + 32 + 16) {")
binary_end = mesh.index(" } else if (cmd_frame[0] == CMD_SIGN_START)", binary_start)
methods += ("\nvoid MyMesh::applyChannelFrame(const uint8_t* cmd_frame, size_t len) {\n"
" if (false) {\n" + mesh[binary_start:binary_end] + "\n }\n}\n")
source = tx.HARNESS[:tx.HARNESS.index("int main() {")]
source = source.replace("#if defined(STM32_PLATFORM)\n#define ATOMIC_FILE_WRITER_IMPLEMENTATION",
"#if defined(STM32_PLATFORM) || defined(NRF52_PLATFORM)\n#define ATOMIC_FILE_WRITER_IMPLEMENTATION", 1)
source = source.replace("#define MESH_DEBUG_PRINTLN(...) ((void)0)", """
#define MESH_DEBUG_PRINTLN(...) ((void)0)
static int last_channel_outcome = -1;
enum { CMD_SET_CHANNEL = 32, ERR_CODE_ILLEGAL_ARG = 1, ERR_CODE_BAD_STATE = 2,
ERR_CODE_UNSUPPORTED_CMD = 3, ERR_CODE_NOT_FOUND = 4, ERR_CODE_FILE_IO_ERROR = 5 };
struct StrHelper {
static void strncpy(char* target, const char* from, size_t size) {
::strncpy(target, from, size - 1); target[size - 1] = 0;
}
};
""", 1)
source = source.replace(" bool _channel_load_incomplete=false;", """
bool _channel_load_incomplete=false;
#if defined(NRF52_PLATFORM)
bool _contact_load_incomplete=false;
struct { bool empty() const { return true; } } _unread_contact_pages;
#endif
""", 1)
source = source.replace(" bool handleTxRoutingCommand(const char*,char*,size_t);", """
bool handleTxRoutingCommand(const char*,char*,size_t);
int last_error = 0;
bool binary_ack = false;
void writeErrFrame(int error) { last_error = error; }
void writeOKFrame() { binary_ack = true; }
void seedEmergencyChannelNotice(uint8_t, const ChannelDetails&) {}
bool resolveChannelAlias(ChannelDetails&) const { return true; }
void applyChannelFrame(const uint8_t*, size_t);
""", 1)
source = source.replace("@RECOVERY_METHOD@", method(header, " bool contactRecoveryPending() const"))
source = source.replace("@CHANNEL_METHOD@", method(header, " bool hasIncompleteChannelLoad() const"))
source = source.replace("@METHODS@", """
#if defined(NRF52_PLATFORM)
static bool contactPathPresence(FILESYSTEM* fs, const char* path, bool& present, uint32_t* size = nullptr) {
present = fs->exists(path);
if (size) *size = present ? fs->files.at(path).size() : 0;
return true;
}
#endif
""" + methods)
source += (ROOT / "test/fixtures/companion_channel_publication/checks.h").read_text()
generated = work / "test.cpp"
generated.write_text(source)
return generated
class CompanionChannelPublicationTest(unittest.TestCase):
def run_platform(self, platform, missing_latch=False):
with tempfile.TemporaryDirectory(prefix="mesh-channel-publication-") as directory:
work = Path(directory)
fixture = publication_fixture(work, missing_latch)
binary = work / "test"
compiled = subprocess.run([
"g++", "-std=c++17", "-O1", "-g", "-Wall", "-Wextra", "-D" + platform + "=1",
"-DMESH_CONTACT_CACHE=0", "-DMESH_ENABLE_MESHTEXT_CHAT=0",
"-fsanitize=address,undefined", "-fno-sanitize-recover=all", "-fno-pie", "-no-pie",
"-I", str(work), "-I", str(ROOT / "test/fixtures/radio_profiles/mocks"),
"-I", str(ROOT / "test/mocks"), "-I", str(ROOT / "src"), "-I", str(ROOT / "src/helpers"),
str(fixture), "-o", str(binary),
], capture_output=True, text=True, timeout=60)
self.assertEqual(compiled.returncode, 0, compiled.stdout + compiled.stderr)
result = subprocess.run([str(binary)], capture_output=True, text=True, timeout=10)
if missing_latch:
self.assertNotEqual(result.returncode, 0)
self.assertIn('strstr(reply, "storage unavailable")', result.stderr)
else:
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertIn("PASS: channel publication authority", result.stdout)
def test_atomic_stm32_publication_and_retry_controls(self):
self.run_platform("STM32_PLATFORM")
def test_atomic_nrf52_publication_and_retry_controls(self):
self.run_platform("NRF52_PLATFORM")
def test_esp32_namespace_and_constructor_uncertainty(self):
self.run_platform("ESP32_PLATFORM")
def test_rp2040_namespace_and_constructor_uncertainty(self):
self.run_platform("RP2040_PLATFORM")
def test_missing_stm32_publication_latch_is_detected(self):
self.run_platform("STM32_PLATFORM", missing_latch=True)
def test_missing_nrf52_publication_latch_is_detected(self):
self.run_platform("NRF52_PLATFORM", missing_latch=True)
def test_missing_esp32_publication_latch_is_detected(self):
self.run_platform("ESP32_PLATFORM", missing_latch=True)
def test_missing_rp2040_publication_latch_is_detected(self):
self.run_platform("RP2040_PLATFORM", missing_latch=True)
if __name__ == "__main__":
unittest.main()
+21 -1
View File
@@ -94,6 +94,16 @@ public:
};
@METHODS@
static void reloadChannelsAfterReboot(MyMesh& node) {
const auto disk=node.store.fs.files;
node.store=DataStore{};
node.store.fs.files=disk;
#if defined(STM32_PLATFORM)
node.store.fs.rename_replaces=true;
#endif
node.store.loadChannels(&node);
}
int main() {
MyMesh node;
#if defined(STM32_PLATFORM)
@@ -211,6 +221,15 @@ int main() {
cmd("set tx.channel 0 off"); assert(strstr(reply,"not saved"));
assert(node.channels[0].channel.tx_radio==mesh::RADIO_TX_BOTH);
assert(node.store.fs.files["/channels2"]==disk);
#if defined(STM32_PLATFORM)
// Atomic rename failure has unknown publication authority even when this
// particular backend seam retained the old bytes. Only fresh load clears it.
assert(node.store.hasIncompleteChannelLoad()&&!node.store.hasIncompleteContactLoad());
cmd("set tx.channel 0 both"); assert(strstr(reply,"storage unavailable"));
reloadChannelsAfterReboot(node);
#else
assert(!node.store.hasIncompleteChannelLoad()); // Confirmed CFT rollback.
#endif
}
#if !defined(STM32_PLATFORM)
// If both publish and rollback fail, the verified backup remains available
@@ -240,7 +259,8 @@ int main() {
assert(failed_boot.store.fs.files["/channels2.bak"]==disk);
#endif
node.store.fs.fail_rename_from.clear();
node.store.loadChannels(&node);
assert(node.store.hasIncompleteChannelLoad()&&!node.store.hasIncompleteContactLoad());
reloadChannelsAfterReboot(node);
assert(!node.store.hasIncompleteContactLoad());
assert(node.store.fs.files["/channels2"]==disk);
assert(node.channels[0].channel.tx_radio==mesh::RADIO_TX_BOTH);