feat(mqtt): implement downgrade contract for MQTT preferences

Enhance the MQTT preferences handling by establishing a downgrade
contract that ensures compatibility between different firmware versions.
This contract allows nodes to read settings from newer builds while
safeguarding against data loss during downgrades. The implementation
includes updates to the classification logic, ensuring that longer
payloads from newer versions are handled correctly without rejecting
files, thus preserving critical WiFi credentials and broker settings.
This commit is contained in:
agessaman committed 2026-07-28 09:03:19 -07:00
1 parent 52bd27190f
commit ecbb5005e9
6 files changed
+151 -34

No files matched your search

+10
View File
@@ -793,6 +793,16 @@ void CommonCLI::loadMQTTPrefs(
MESH_DEBUG_PRINTLN("MQTT: /mqtt_prefs read failed, using defaults (file preserved)");
} else {
has_observer_fields = plan.observer_fields_present;
// Written by a later build with appended fields. Everything this
// binary knows loaded normally; say so, because the next `set` will
// rewrite the file at this length and drop the newer settings.
if (file_size - sizeof(MQTTPrefsHeader) > plan.payload_len) {
MESH_DEBUG_PRINTLN(
"MQTT: /mqtt_prefs written by newer firmware (%u > %u bytes); "
"config loaded, newer settings ignored and dropped on next save",
(unsigned)(file_size - sizeof(MQTTPrefsHeader)),
(unsigned)plan.payload_len);
}
}
if (file) file.close();
} else if (plan.rewrite_legacy) {
+19 -3
View File
@@ -114,10 +114,26 @@ inline DecodePlan classify(const uint8_t* prefix, size_t prefix_read, size_t fil
if (header.payload_len != payload_available) {
return corruptPlan();
}
// A same-version append is still unknown to this binary. Holding the
// file prevents a downgrade from discarding it on the next CLI save.
// A longer same-version payload was written by a later build that
// appended fields. Within a version tag the layout is append-only, so
// every byte this binary knows is present and correctly positioned — read
// the baseline prefix and ignore the tail.
//
// This is the downgrade contract, and it is deliberately asymmetric:
// refusing the file would cost the operator WiFi credentials and every
// broker slot (a node with no network and no portal, recoverable only
// over serial), whereas reading it costs only the settings the newer
// build added. Losing a later feature's settings is the acceptable half.
//
// The tail survives until something actually writes: saveMQTTPrefs()
// rewrites at this binary's own length, so a rollback that changes no
// observer setting and is later rolled forward keeps the newer fields
// intact. Only an explicit `set` while downgraded drops them.
//
// A layout change that is NOT a pure append must bump MQTT_PREFS_VERSION;
// the version check above is what makes this rule safe.
if (header.payload_len > kV1BaselinePayloadSize) {
return {Source::UnsupportedVersion, false, true, false, 0};
return {Source::Current, false, false, true, kV1BaselinePayloadSize};
}
if (header.payload_len == kV1BaselinePayloadSize) {
return {Source::Current, false, false, true, kV1BaselinePayloadSize};
+8 -1
View File
@@ -135,7 +135,14 @@ static const uint32_t MQTT_NEIGHBORS_MAX_INTERVAL_MS = MQTT_NEIGHBORS_MAX_INTERV
static const uint32_t MQTT_NEIGHBORS_DEFAULT_INTERVAL_MS = MQTT_NEIGHBORS_DEFAULT_INTERVAL_HOURS * 3600000UL;
// Version-1 has four payload layouts this firmware can decode. Never infer a
// compatible payload from an arbitrary shorter size: raw prefs have no checksum.
// compatible payload from an arbitrary SHORTER size: raw prefs have no
// checksum, so a short length has to match a boundary that was really shipped.
//
// A LONGER v1 payload is different and is always readable: within a version tag
// the layout is append-only, so a later build's file still starts with this
// binary's exact baseline. classify() reads that prefix and ignores the tail
// rather than rejecting the file — see the downgrade contract there. Any change
// that is not a pure append MUST bump MQTT_PREFS_VERSION instead.
// - PRE_OBSERVER (2736): stops before the observer tail (snmp_*/alert_*).
// - PRE_NEIGHBORS (2860): full observer tail, no neighbors fields yet.
// - PRE_FILTER (2864): neighbors tail, no per-slot packet filters.