@alteriom/painlessmesh 1.8.15 → 1.9.0

package/docs/releases/PATCH_v1.7.2.md

@@ -1,262 +0,0 @@
-# Patch Release v1.7.2
-
-**Release Date:** 2025-10-16  
-**Type:** Critical Bug Fix  
-**Branch:** main
-
-## Overview
-
-This patch release addresses a critical memory safety issue in the router JSON parsing logic that could lead to segmentation faults and unbounded memory growth.
-
----
-
-## Critical Fix
-
-### Router JSON Parsing Segmentation Fault (P0)
-
-**Issue:** The router used a workaround for a segmentation fault bug that involved dynamically growing memory capacity from 512B to 20KB through repeated allocations, causing:
-
-- Memory leaks from abandoned `shared_ptr` allocations
-- Unbounded memory growth (static variable never reset)
-- Performance degradation on large packets
-- Risk of OOM crashes on ESP8266 (80KB heap)
-
-**Root Cause:** The original code attempted to work around an ArduinoJson copy constructor bug by repeatedly reallocating with larger capacities until parsing succeeded or capacity reached 20KB.
-
-**Solution Implemented:**
-
-1. **Pre-calculated Capacity:** Calculate required capacity upfront based on message size and nesting depth
-2. **Version-Aware:** Different strategies for ArduinoJson v6 vs v7
-3. **Safety Cap:** Maximum 8KB capacity to protect ESP8266 from OOM
-4. **Better Error Handling:** Clear error messages when messages exceed capacity
-5. **No Static State:** Eliminated the static `baseCapacity` variable
-
----
-
-## Changes
-
-### Modified Files
-
-#### src/painlessmesh/router.hpp (Lines 192-221)
-
-```cpp
-// Before (v1.7.0):
-static size_t baseCapacity = 512;
-auto variant = std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-while (variant->error == DeserializationError::NoMemory && baseCapacity <= 20480) {
-    baseCapacity += 256;
-    variant = std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-}
-
-// After (v1.7.2):
-size_t nestingDepth = std::count(pkg.begin(), pkg.end(), '{') + 
-                      std::count(pkg.begin(), pkg.end(), '[']);
-
-#if ARDUINOJSON_VERSION_MAJOR >= 7
-  size_t calculatedCapacity = pkg.length() + 1024;
-#else
-  size_t calculatedCapacity = pkg.length() + 
-                              JSON_OBJECT_SIZE(10) * std::max(nestingDepth, size_t(1)) + 
-                              512;
-#endif
-
-constexpr size_t MAX_MESSAGE_CAPACITY = 8192;
-size_t capacity = std::min(calculatedCapacity, MAX_MESSAGE_CAPACITY);
-auto variant = std::make_shared<protocol::Variant>(pkg, capacity);
-```
-
-### New Files
-
-#### test/catch/catch_router_memory.cpp
-
-- Comprehensive tests for JSON parsing capacity calculation
-- Tests for deeply nested messages
-- Tests for oversized messages
-- Tests for predictable memory allocation patterns
-
-#### docs/development/CODE_REFACTORING_RECOMMENDATIONS.md
-
-- Comprehensive code analysis document
-- 8 prioritized refactoring recommendations (P0-P3)
-- Implementation roadmap for v1.7.1 → v2.0.0
-- Testing strategies and metrics
-
----
-
-## Testing
-
-### Test Results
-
-All tests passing:
-
-```
-✓ catch_alteriom_packages: 80 assertions in 7 test cases
-✓ catch_base64: 2 assertions in 1 test case
-✓ catch_buffer: 57 assertions in 2 test cases
-✓ catch_callback: 6 assertions in 1 test case
-✓ catch_connection: 6 assertions in 1 test case
-✓ catch_layout: 25 assertions in 5 test cases
-✓ catch_logger: 1 test case passed
-✓ catch_metrics: 40 assertions in 5 test cases
-✓ catch_mqtt_bridge: 59 assertions in 7 test cases
-✓ catch_ntp: No tests (empty)
-✓ catch_plugin: 25 assertions in 3 test cases
-✓ catch_protocol: 187 assertions in 9 test cases
-✓ catch_router: No tests (empty)
-✓ catch_router_memory: 14 assertions in 2 test cases ← NEW
-✓ catch_tcp: 3 assertions in 1 test case
-✓ catch_tcp_integration: 113 assertions in 8 test cases
-✓ catch_topology_schema: 16 assertions in 3 test cases
-✓ catch_validation: 17 assertions in 4 test cases
-```
-
-**Total:** 710+ assertions passed
-
-### Memory Safety Verification
-
-The new tests verify:
-
-1. **Simple messages** parse correctly with minimal capacity
-2. **Deeply nested messages** (10+ levels) get appropriate capacity
-3. **Oversized messages** are capped at MAX_MESSAGE_CAPACITY
-4. **Capacity calculation** is predictable and doesn't grow unbounded
-
----
-
-## Performance Impact
-
-### Memory Usage (Before → After)
-
-| Scenario | v1.7.0 | v1.7.2 | Change |
-|----------|--------|--------|--------|
-| Small message (50B) | 562B | 1074B | +512B |
-| Medium message (500B) | 1012B → 5120B* | 1524B | -3596B* |
-| Large message (2KB) | 2560B → 20KB* | 3072B | -17KB* |
-| Nested message (10 levels) | variable | ~4KB | predictable |
-
-*v1.7.0 would retry with growing capacity, potentially reaching 20KB
-
-### Benefits
-
-1. **No Memory Leaks:** Single allocation per message, no abandoned allocations
-2. **Predictable:** Capacity calculated once, no runtime growth
-3. **ESP8266 Safe:** 8KB cap prevents OOM on 80KB heap devices
-4. **Better Errors:** Clear messages when capacity exceeded
-
----
-
-## Migration Guide
-
-### For Users
-
-**No action required** - this is a transparent bug fix.
-
-**If you see errors:**
-
-```text
-ERROR: routePackage(): Message too large. length=10000, calculated_capacity=12000, nesting_depth=5
-```
-
-**Options:**
-
-1. Reduce message size (recommended)
-2. Increase `MAX_MESSAGE_CAPACITY` in `router.hpp` (only if you have sufficient heap)
-3. Split large messages into smaller chunks
-
-### For Developers
-
-**If extending mesh protocol:**
-
-- Keep messages under 8KB total size
-- Limit JSON nesting to < 20 levels
-- Test with `catch_router_memory` tests
-- Monitor heap usage with `ESP.getFreeHeap()`
-
----
-
-## Known Limitations
-
-1. **8KB Message Limit:** Messages larger than 8KB will be rejected
-   - **Workaround:** Split into multiple messages
-   - **Future:** May increase on ESP32 (320KB heap) in v2.0
-
-2. **Deep Nesting Overhead:** Each nesting level adds ~200B overhead
-   - **Workaround:** Flatten JSON structures where possible
-   - **Impact:** 20-level nesting ≈ 4KB overhead
-
----
-
-## References
-
-### Related Issues
-
-- #521 - ArduinoJson copy constructor segmentation fault
-- [CODE_REFACTORING_RECOMMENDATIONS.md](../development/CODE_REFACTORING_RECOMMENDATIONS.md) - Full analysis
-
-### Related Documentation
-
-- [Router API](../api/router.md)
-- [Protocol Specification](../api/protocol.md)
-- [Memory Management](../troubleshooting/memory.md)
-
----
-
-## Upgrade Instructions
-
-### PlatformIO
-
-```ini
-[env:esp32]
-lib_deps =
-    https://github.com/Alteriom/painlessMesh.git#v1.7.2
-```
-
-### Arduino IDE
-
-1. Open Library Manager
-2. Search for "painlessMesh"
-3. Update to v1.7.2
-
-### Manual
-
-```bash
-cd ~/Arduino/libraries/painlessMesh
-git fetch
-git checkout v1.7.2
-```
-
----
-
-## Checksums
-
-**Release Archive:** `painlessMesh-v1.7.2.zip`
-
-```text
-MD5: [to be generated]
-SHA256: [to be generated]
-```
-
----
-
-## Credits
-
-**Fixed By:** GitHub Copilot + Alteriom Team  
-**Reported By:** Community (via segfault reports)  
-**Tested By:** Docker test suite (Linux x86_64)
-
----
-
-## Next Steps
-
-See [CODE_REFACTORING_RECOMMENDATIONS.md](../development/CODE_REFACTORING_RECOMMENDATIONS.md) for planned improvements in v1.8.0 and v2.0.0:
-
-- **P1:** Implement hop count calculation (v1.8.0)
-- **P1:** Implement routing table for multi-hop paths (v1.8.0)
-- **P2:** Remove deprecated CONTROL message type (v1.9.0)
-- **P3:** Improve NTP middle node behavior (v1.9.0)
-
----
-
-**Document Status:** ✅ Complete  
-**Release Status:** 🚀 Ready for Tagging  
-**Next Release:** v1.8.0 (Planned: Q1 2026)

package/docs/releases/PATCH_v1.7.3.md

@@ -1,262 +0,0 @@
-# Patch Release v1.7.3
-
-**Release Date:** 2025-10-16  
-**Type:** Critical Bug Fix  
-**Branch:** main
-
-## Overview
-
-This patch release addresses a critical memory safety issue in the router JSON parsing logic that could lead to segmentation faults and unbounded memory growth.
-
----
-
-## Critical Fix
-
-### Router JSON Parsing Segmentation Fault (P0)
-
-**Issue:** The router used a workaround for a segmentation fault bug that involved dynamically growing memory capacity from 512B to 20KB through repeated allocations, causing:
-
-- Memory leaks from abandoned `shared_ptr` allocations
-- Unbounded memory growth (static variable never reset)
-- Performance degradation on large packets
-- Risk of OOM crashes on ESP8266 (80KB heap)
-
-**Root Cause:** The original code attempted to work around an ArduinoJson copy constructor bug by repeatedly reallocating with larger capacities until parsing succeeded or capacity reached 20KB.
-
-**Solution Implemented:**
-
-1. **Pre-calculated Capacity:** Calculate required capacity upfront based on message size and nesting depth
-2. **Version-Aware:** Different strategies for ArduinoJson v6 vs v7
-3. **Safety Cap:** Maximum 8KB capacity to protect ESP8266 from OOM
-4. **Better Error Handling:** Clear error messages when messages exceed capacity
-5. **No Static State:** Eliminated the static `baseCapacity` variable
-
----
-
-## Changes
-
-### Modified Files
-
-#### src/painlessmesh/router.hpp (Lines 192-221)
-
-```cpp
-// Before (v1.7.0):
-static size_t baseCapacity = 512;
-auto variant = std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-while (variant->error == DeserializationError::NoMemory && baseCapacity <= 20480) {
-    baseCapacity += 256;
-    variant = std::make_shared<protocol::Variant>(pkg, pkg.length() + baseCapacity);
-}
-
-// After (v1.7.3):
-size_t nestingDepth = std::count(pkg.begin(), pkg.end(), '{') + 
-                      std::count(pkg.begin(), pkg.end(), '[']);
-
-#if ARDUINOJSON_VERSION_MAJOR >= 7
-  size_t calculatedCapacity = pkg.length() + 1024;
-#else
-  size_t calculatedCapacity = pkg.length() + 
-                              JSON_OBJECT_SIZE(10) * std::max(nestingDepth, size_t(1)) + 
-                              512;
-#endif
-
-constexpr size_t MAX_MESSAGE_CAPACITY = 8192;
-size_t capacity = std::min(calculatedCapacity, MAX_MESSAGE_CAPACITY);
-auto variant = std::make_shared<protocol::Variant>(pkg, capacity);
-```
-
-### New Files
-
-#### test/catch/catch_router_memory.cpp
-
-- Comprehensive tests for JSON parsing capacity calculation
-- Tests for deeply nested messages
-- Tests for oversized messages
-- Tests for predictable memory allocation patterns
-
-#### docs/development/CODE_REFACTORING_RECOMMENDATIONS.md
-
-- Comprehensive code analysis document
-- 8 prioritized refactoring recommendations (P0-P3)
-- Implementation roadmap for v1.7.1 → v2.0.0
-- Testing strategies and metrics
-
----
-
-## Testing
-
-### Test Results
-
-All tests passing:
-
-```
-✓ catch_alteriom_packages: 80 assertions in 7 test cases
-✓ catch_base64: 2 assertions in 1 test case
-✓ catch_buffer: 57 assertions in 2 test cases
-✓ catch_callback: 6 assertions in 1 test case
-✓ catch_connection: 6 assertions in 1 test case
-✓ catch_layout: 25 assertions in 5 test cases
-✓ catch_logger: 1 test case passed
-✓ catch_metrics: 40 assertions in 5 test cases
-✓ catch_mqtt_bridge: 59 assertions in 7 test cases
-✓ catch_ntp: No tests (empty)
-✓ catch_plugin: 25 assertions in 3 test cases
-✓ catch_protocol: 187 assertions in 9 test cases
-✓ catch_router: No tests (empty)
-✓ catch_router_memory: 14 assertions in 2 test cases ← NEW
-✓ catch_tcp: 3 assertions in 1 test case
-✓ catch_tcp_integration: 113 assertions in 8 test cases
-✓ catch_topology_schema: 16 assertions in 3 test cases
-✓ catch_validation: 17 assertions in 4 test cases
-```
-
-**Total:** 710+ assertions passed
-
-### Memory Safety Verification
-
-The new tests verify:
-
-1. **Simple messages** parse correctly with minimal capacity
-2. **Deeply nested messages** (10+ levels) get appropriate capacity
-3. **Oversized messages** are capped at MAX_MESSAGE_CAPACITY
-4. **Capacity calculation** is predictable and doesn't grow unbounded
-
----
-
-## Performance Impact
-
-### Memory Usage (Before → After)
-
-| Scenario | v1.7.0 | v1.7.3 | Change |
-|----------|--------|--------|--------|
-| Small message (50B) | 562B | 1074B | +512B |
-| Medium message (500B) | 1012B → 5120B* | 1524B | -3596B* |
-| Large message (2KB) | 2560B → 20KB* | 3072B | -17KB* |
-| Nested message (10 levels) | variable | ~4KB | predictable |
-
-*v1.7.0 would retry with growing capacity, potentially reaching 20KB
-
-### Benefits
-
-1. **No Memory Leaks:** Single allocation per message, no abandoned allocations
-2. **Predictable:** Capacity calculated once, no runtime growth
-3. **ESP8266 Safe:** 8KB cap prevents OOM on 80KB heap devices
-4. **Better Errors:** Clear messages when capacity exceeded
-
----
-
-## Migration Guide
-
-### For Users
-
-**No action required** - this is a transparent bug fix.
-
-**If you see errors:**
-
-```text
-ERROR: routePackage(): Message too large. length=10000, calculated_capacity=12000, nesting_depth=5
-```
-
-**Options:**
-
-1. Reduce message size (recommended)
-2. Increase `MAX_MESSAGE_CAPACITY` in `router.hpp` (only if you have sufficient heap)
-3. Split large messages into smaller chunks
-
-### For Developers
-
-**If extending mesh protocol:**
-
-- Keep messages under 8KB total size
-- Limit JSON nesting to < 20 levels
-- Test with `catch_router_memory` tests
-- Monitor heap usage with `ESP.getFreeHeap()`
-
----
-
-## Known Limitations
-
-1. **8KB Message Limit:** Messages larger than 8KB will be rejected
-   - **Workaround:** Split into multiple messages
-   - **Future:** May increase on ESP32 (320KB heap) in v2.0
-
-2. **Deep Nesting Overhead:** Each nesting level adds ~200B overhead
-   - **Workaround:** Flatten JSON structures where possible
-   - **Impact:** 20-level nesting ≈ 4KB overhead
-
----
-
-## References
-
-### Related Issues
-
-- #521 - ArduinoJson copy constructor segmentation fault
-- [CODE_REFACTORING_RECOMMENDATIONS.md](../development/CODE_REFACTORING_RECOMMENDATIONS.md) - Full analysis
-
-### Related Documentation
-
-- [Router API](../api/router.md)
-- [Protocol Specification](../api/protocol.md)
-- [Memory Management](../troubleshooting/memory.md)
-
----
-
-## Upgrade Instructions
-
-### PlatformIO
-
-```ini
-[env:esp32]
-lib_deps =
-    https://github.com/Alteriom/painlessMesh.git#v1.7.3
-```
-
-### Arduino IDE
-
-1. Open Library Manager
-2. Search for "painlessMesh"
-3. Update to v1.7.3
-
-### Manual
-
-```bash
-cd ~/Arduino/libraries/painlessMesh
-git fetch
-git checkout v1.7.3
-```
-
----
-
-## Checksums
-
-**Release Archive:** `painlessMesh-v1.7.3.zip`
-
-```text
-MD5: [to be generated]
-SHA256: [to be generated]
-```
-
----
-
-## Credits
-
-**Fixed By:** GitHub Copilot + Alteriom Team  
-**Reported By:** Community (via segfault reports)  
-**Tested By:** Docker test suite (Linux x86_64)
-
----
-
-## Next Steps
-
-See [CODE_REFACTORING_RECOMMENDATIONS.md](../development/CODE_REFACTORING_RECOMMENDATIONS.md) for planned improvements in v1.8.0 and v2.0.0:
-
-- **P1:** Implement hop count calculation (v1.8.0)
-- **P1:** Implement routing table for multi-hop paths (v1.8.0)
-- **P2:** Remove deprecated CONTROL message type (v1.9.0)
-- **P3:** Improve NTP middle node behavior (v1.9.0)
-
----
-
-**Document Status:** ✅ Complete  
-**Release Status:** 🚀 Ready for Tagging  
-**Next Release:** v1.8.0 (Planned: Q1 2026)