From 33af8ecc05d6d44c83b2c5ceb16c56c0745f9936 Mon Sep 17 00:00:00 2001 From: TeTeHacko Date: Sat, 5 Sep 2026 23:39:04 +0200 Subject: [PATCH] feat(repeater): fairness grid viditelnost + runtime cap/refill tuning Co-Authored-By: Claude Fable 5 --- examples/simple_repeater/MyMesh.cpp | 113 ++++++++++++++---- examples/simple_repeater/MyMesh.h | 14 ++- src/helpers/CommonCLI.h | 9 ++ src/helpers/FairnessLimiter.cpp | 50 ++++++++ src/helpers/FairnessLimiter.h | 23 +++- .../test_fairness_limiter.cpp | 49 ++++++++ 6 files changed, 231 insertions(+), 27 deletions(-) diff --git a/examples/simple_repeater/MyMesh.cpp b/examples/simple_repeater/MyMesh.cpp index 71ad2bf6..2e7aec59 100644 --- a/examples/simple_repeater/MyMesh.cpp +++ b/examples/simple_repeater/MyMesh.cpp @@ -724,26 +724,85 @@ bool MyMesh::allowPacketForward(const mesh::Packet *packet) { return true; } -// CUSTOM (TeTeHacko): `fairness` -- denied-forward stats; `fairness on|off` -- -// runtime kill switch (persisted, so a mast reboot keeps the chosen state). -bool MyMesh::fairnessHandleCommand(const char *command, char *reply) { +// CUSTOM (TeTeHacko): `fairness` -- denied-forward stats + current caps; +// `fairness on|off` -- runtime kill switch (persisted). +// `fairness grid` -- busiest deny buckets per category (what we shed). +// `fairness cap ` -- burst caps, 0 = default. +// `fairness refill ` -- refill interval secs, 0 = default. +// All tuning is persisted, so a mast reboot keeps it. +bool MyMesh::fairnessHandleCommand(const char *command, char *reply, int reply_max) { if (memcmp(command, "fairness", 8) != 0 || (command[8] != 0 && command[8] != ' ')) return false; - if (command[8] == ' ') { - const char *arg = &command[9]; - if (strcmp(arg, "on") == 0 || strcmp(arg, "off") == 0) { - _prefs.fairness_enabled = (arg[1] == 'n') ? 1 : 0; - savePrefs(); - sprintf(reply, "OK - fairness %s", _prefs.fairness_enabled ? "on" : "off"); - } else { - strcpy(reply, "Err - fairness [on|off]"); - } + const char *arg = (command[8] == ' ') ? &command[9] : ""; + + if (strcmp(arg, "on") == 0 || strcmp(arg, "off") == 0) { + _prefs.fairness_enabled = (arg[1] == 'n') ? 1 : 0; + savePrefs(); + sprintf(reply, "OK - fairness %s", _prefs.fairness_enabled ? "on" : "off"); return true; } - sprintf(reply, "fairness: %s, denied group %u, sender %u, advert %u", - _prefs.fairness_enabled ? "on" : "OFF", - fairness_limiter.deniedGroup(), fairness_limiter.deniedSenderNormal(), - fairness_limiter.deniedSenderLow()); + + if (strcmp(arg, "grid") == 0) { + char grid[180]; + fairness_limiter.formatGrid(grid, sizeof(grid)); + snprintf(reply, reply_max, "%s", grid); + return true; + } + + if (memcmp(arg, "cap ", 4) == 0) { + int g = 0, s = 0, a = 0; + if (sscanf(arg + 4, "%d %d %d", &g, &s, &a) != 3 || g < 0 || s < 0 || a < 0 || g > 255 || s > 255 || a > 255) { + strcpy(reply, "Err - fairness cap (0=default)"); + return true; + } + _prefs.fair_group_cap = (uint8_t)g; + _prefs.fair_sender_cap = (uint8_t)s; + _prefs.fair_advert_cap = (uint8_t)a; + fairness_limiter.setGroupCap(_prefs.fair_group_cap); + fairness_limiter.setSenderNormalCap(_prefs.fair_sender_cap); + fairness_limiter.setSenderLowCap(_prefs.fair_advert_cap); + savePrefs(); + sprintf(reply, "OK - cap group %u sender %u advert %u", + (uint32_t)fairness_limiter.groupCap(), (uint32_t)fairness_limiter.senderNormalCap(), + (uint32_t)fairness_limiter.senderLowCap()); + return true; + } + + if (memcmp(arg, "refill ", 7) == 0) { + int g = 0, s = 0, a = 0; + if (sscanf(arg + 7, "%d %d %d", &g, &s, &a) != 3 || g < 0 || s < 0 || a < 0 || g > 65535 || s > 65535 || a > 65535) { + strcpy(reply, "Err - fairness refill (0=default)"); + return true; + } + _prefs.fair_group_refill_s = (uint16_t)g; + _prefs.fair_sender_refill_s = (uint16_t)s; + _prefs.fair_advert_refill_s = (uint16_t)a; + // reschedule so the new interval takes effect from now + next_fair_group_refill = futureMillis(fairGroupRefillMs()); + next_fair_sender_normal_refill = futureMillis(fairSenderRefillMs()); + next_fair_sender_low_refill = futureMillis(fairAdvertRefillMs()); + savePrefs(); + sprintf(reply, "OK - refill group %us sender %us advert %us", + (uint32_t)(fairGroupRefillMs() / 1000), (uint32_t)(fairSenderRefillMs() / 1000), + (uint32_t)(fairAdvertRefillMs() / 1000)); + return true; + } + + if (arg[0] != 0) { + strcpy(reply, "Err - fairness [on|off|grid|cap ...|refill ...]"); + return true; + } + + // bare `fairness` -- stats + current caps/refills + snprintf(reply, reply_max, + "fairness: %s, denied group %u/sender %u/advert %u; cap %u/%u/%u; refill %u/%u/%us", + _prefs.fairness_enabled ? "on" : "OFF", + fairness_limiter.deniedGroup(), fairness_limiter.deniedSenderNormal(), + fairness_limiter.deniedSenderLow(), + (uint32_t)fairness_limiter.groupCap(), (uint32_t)fairness_limiter.senderNormalCap(), + (uint32_t)fairness_limiter.senderLowCap(), + (uint32_t)(fairGroupRefillMs() / 1000), (uint32_t)(fairSenderRefillMs() / 1000), + (uint32_t)(fairAdvertRefillMs() / 1000)); return true; } @@ -1328,14 +1387,20 @@ void MyMesh::begin(FILESYSTEM *fs) { _cli.loadPrefs(_fs); acl.load(_fs, self_id); + // Apply any persisted runtime cap tuning (0 = build default). Do this before + // the first refill so the initial token respects a raised cap. + fairness_limiter.setGroupCap(_prefs.fair_group_cap); + fairness_limiter.setSenderNormalCap(_prefs.fair_sender_cap); + fairness_limiter.setSenderLowCap(_prefs.fair_advert_cap); + // Fairness buckets start with just ONE token (not the full cap): a repeater // stuck in a crash loop must not hand out a fresh burst on every boot. fairness_limiter.refillSenderNormal(); fairness_limiter.refillSenderLow(); fairness_limiter.refillGroup(); - next_fair_sender_normal_refill = futureMillis(FAIRNESS_SENDER_NORMAL_REFILL_MS); - next_fair_sender_low_refill = futureMillis(FAIRNESS_SENDER_LOW_REFILL_MS); - next_fair_group_refill = futureMillis(FAIRNESS_GROUP_REFILL_MS); + next_fair_sender_normal_refill = futureMillis(fairSenderRefillMs()); + next_fair_sender_low_refill = futureMillis(fairAdvertRefillMs()); + next_fair_group_refill = futureMillis(fairGroupRefillMs()); // TODO: key_store.begin(); region_map.load(_fs); @@ -1700,8 +1765,8 @@ void MyMesh::handleCommand(uint32_t sender_timestamp, char *command, char *reply // channel messages this repeater refuses to forward. See ChannelFilter.h. if (filterHandleCommand(command, reply, reply_max)) return; #endif - // CUSTOM (TeTeHacko): `fairness [on|off]` — forwarding rate limiter stats + kill switch. - if (fairnessHandleCommand(command, reply)) return; + // CUSTOM (TeTeHacko): `fairness [on|off|grid|cap ...|refill ...]` — rate limiter. + if (fairnessHandleCommand(command, reply, reply_max)) return; // CUSTOM (TeTeHacko): `blink [n]` — flash the LED to identify this board. // Outside the BLE guard on purpose: a USB-only build needs it just as much, // since a board with no data cable and no BLE cannot be identified at all. @@ -1742,13 +1807,13 @@ void MyMesh::loop() { // aligning on one loop pass; each adds ONE token per bucket per interval. if (next_fair_sender_normal_refill && millisHasNowPassed(next_fair_sender_normal_refill)) { fairness_limiter.refillSenderNormal(); - next_fair_sender_normal_refill = futureMillis(FAIRNESS_SENDER_NORMAL_REFILL_MS); + next_fair_sender_normal_refill = futureMillis(fairSenderRefillMs()); } else if (next_fair_sender_low_refill && millisHasNowPassed(next_fair_sender_low_refill)) { fairness_limiter.refillSenderLow(); - next_fair_sender_low_refill = futureMillis(FAIRNESS_SENDER_LOW_REFILL_MS); + next_fair_sender_low_refill = futureMillis(fairAdvertRefillMs()); } else if (next_fair_group_refill && millisHasNowPassed(next_fair_group_refill)) { fairness_limiter.refillGroup(); - next_fair_group_refill = futureMillis(FAIRNESS_GROUP_REFILL_MS); + next_fair_group_refill = futureMillis(fairGroupRefillMs()); } if (next_flood_advert && millisHasNowPassed(next_flood_advert)) { diff --git a/examples/simple_repeater/MyMesh.h b/examples/simple_repeater/MyMesh.h index 7f194ac0..56bbf44c 100644 --- a/examples/simple_repeater/MyMesh.h +++ b/examples/simple_repeater/MyMesh.h @@ -319,8 +319,18 @@ class MyMesh : public mesh::Mesh, public CommonCLICallbacks { bool botPeerAllowed(const char* name); bool botHandleCommand(const char* command, char* reply); #endif - // CUSTOM (TeTeHacko): `fairness [on|off]` CLI. Defined in MyMesh.cpp. - bool fairnessHandleCommand(const char* command, char* reply); + // CUSTOM (TeTeHacko): `fairness [on|off|grid|cap ...|refill ...]` CLI. Defined in MyMesh.cpp. + bool fairnessHandleCommand(const char* command, char* reply, int reply_max); + // Refill interval in ms: persisted pref (seconds) if set, else the build default. + uint32_t fairGroupRefillMs() const { + return _prefs.fair_group_refill_s ? (uint32_t)_prefs.fair_group_refill_s * 1000 : FAIRNESS_GROUP_REFILL_MS; + } + uint32_t fairSenderRefillMs() const { + return _prefs.fair_sender_refill_s ? (uint32_t)_prefs.fair_sender_refill_s * 1000 : FAIRNESS_SENDER_NORMAL_REFILL_MS; + } + uint32_t fairAdvertRefillMs() const { + return _prefs.fair_advert_refill_s ? (uint32_t)_prefs.fair_advert_refill_s * 1000 : FAIRNESS_SENDER_LOW_REFILL_MS; + } uint8_t handleLoginReq(const mesh::Identity& sender, const uint8_t* secret, uint32_t sender_timestamp, const uint8_t* data, bool is_flood); uint8_t handleAnonRegionsReq(const mesh::Identity& sender, uint32_t sender_timestamp, const uint8_t* data); uint8_t handleAnonOwnerReq(const mesh::Identity& sender, uint32_t sender_timestamp, const uint8_t* data); diff --git a/src/helpers/CommonCLI.h b/src/helpers/CommonCLI.h index 85f3ba47..dc7990a8 100644 --- a/src/helpers/CommonCLI.h +++ b/src/helpers/CommonCLI.h @@ -77,6 +77,9 @@ public: // just leave them at defaults. uint8_t fairness_enabled = 0; // FairnessLimiter runtime kill switch char filter_deny[128]; // channel-filter deny list, comma-separated node names + // FairnessLimiter runtime tuning; 0 = use the firmware build default. + uint8_t fair_group_cap = 0, fair_sender_cap = 0, fair_advert_cap = 0; + uint16_t fair_group_refill_s = 0, fair_sender_refill_s = 0, fair_advert_refill_s = 0; private: class RadioPrefs : public CommonRadioPrefs { @@ -193,6 +196,12 @@ private: def("loop", _parent->loop_detect); def("fair_en", _parent->fairness_enabled); def("f_deny", _parent->filter_deny, sizeof(_parent->filter_deny)); + def("fair_gcap", _parent->fair_group_cap); + def("fair_scap", _parent->fair_sender_cap); + def("fair_acap", _parent->fair_advert_cap); + def("fair_grf", _parent->fair_group_refill_s); + def("fair_srf", _parent->fair_sender_refill_s); + def("fair_arf", _parent->fair_advert_refill_s); } public: RepeatPrefs(NodePrefs* parent) : _parent(parent) { } diff --git a/src/helpers/FairnessLimiter.cpp b/src/helpers/FairnessLimiter.cpp index 21fcb9fd..129feda8 100644 --- a/src/helpers/FairnessLimiter.cpp +++ b/src/helpers/FairnessLimiter.cpp @@ -1,6 +1,8 @@ #include "FairnessLimiter.h" #include +#include +#include uint8_t FairnessLimiter::peekGroup(const uint8_t* hash) { auto i = group_idx(hash); @@ -18,6 +20,7 @@ bool FairnessLimiter::takeGroup(const uint8_t* hash) { allow = true; } else { denied_group++; + if (i < GROUP_MAP_SIZE && group_deny[i] != 0xFFFF) group_deny[i]++; } MESH_DEBUG_PRINTLN("FAIR, group=%02X allow=%u", (uint32_t)hash[0], (uint32_t)allow); return allow; @@ -57,6 +60,7 @@ bool FairnessLimiter::takeSenderNormal(const uint8_t* hash) { allow = true; } else { denied_sender_normal++; + if (i < SENDER_NORMAL_MAP_SIZE && sender_normal_deny[i] != 0xFFFF) sender_normal_deny[i]++; } MESH_DEBUG_PRINTLN("FAIR, sender=%02X prio=normal allow=%u", (uint32_t)hash[0], (uint32_t)allow); return allow; @@ -96,6 +100,7 @@ bool FairnessLimiter::takeSenderLow(const uint8_t* hash) { allow = true; } else { denied_sender_low++; + if (i < SENDER_LOW_MAP_SIZE && sender_low_deny[i] != 0xFFFF) sender_low_deny[i]++; } MESH_DEBUG_PRINTLN("FAIR, sender=%02X prio=low allow=%u", (uint32_t)hash[0], (uint32_t)allow); return allow; @@ -152,3 +157,48 @@ bool FairnessLimiter::allowPacket(const mesh::Packet* pkt) { // PAYLOAD_TYPE_CONTROL, PAYLOAD_TYPE_RAW_CUSTOM return true; } + +// Append the busiest deny buckets of one category to `out`. Repeated max-scan +// over a small array (<=128) -- picks up to `top` entries, busiest first, and +// skips a bucket once emitted by nulling a scratch copy. Returns chars written. +static int fmt_deny_cat(char* out, int max_len, const char* label, + uint16_t* deny, int size, uint8_t cap, int top) { + int w = snprintf(out, max_len, "%s(cap %u):", label, (unsigned)cap); + if (w < 0 || w >= max_len) return (w < 0) ? 0 : max_len - 1; + bool any = false; + for (int n = 0; n < top; n++) { + int best = -1; + uint16_t best_v = 0; + for (int i = 0; i < size; i++) { + if (deny[i] > best_v) { best_v = deny[i]; best = i; } + } + if (best < 0) break; // no non-zero left + int adv = snprintf(out + w, max_len - w, " %02x=%u", (unsigned)best, (unsigned)best_v); + if (adv < 0 || adv >= max_len - w) { out[w] = 0; break; } // no room, stop clean + w += adv; + any = true; + deny[best] = 0; // consumed for the next pass; `deny` is formatGrid's scratch copy + } + if (!any) { + int adv = snprintf(out + w, max_len - w, " -"); + if (adv > 0 && adv < max_len - w) w += adv; + } + return w; +} + +int FairnessLimiter::formatGrid(char* out, int max_len) const { + // Work on scratch copies so the busiest-first selection can null entries as + // it consumes them without disturbing the live counters. + static uint16_t g[GROUP_MAP_SIZE], sn[SENDER_NORMAL_MAP_SIZE], sl[SENDER_LOW_MAP_SIZE]; + memcpy(g, group_deny, sizeof(g)); + memcpy(sn, sender_normal_deny, sizeof(sn)); + memcpy(sl, sender_low_deny, sizeof(sl)); + + int w = 0; + w += fmt_deny_cat(out + w, max_len - w, "group", g, GROUP_MAP_SIZE, group_cap, 6); + if (w < max_len - 2) { int a = snprintf(out + w, max_len - w, " | "); if (a > 0) w += a; } + w += fmt_deny_cat(out + w, max_len - w, "sender", sn, SENDER_NORMAL_MAP_SIZE, sender_normal_cap, 6); + if (w < max_len - 2) { int a = snprintf(out + w, max_len - w, " | "); if (a > 0) w += a; } + w += fmt_deny_cat(out + w, max_len - w, "advert", sl, SENDER_LOW_MAP_SIZE, sender_low_cap, 4); + return w; +} diff --git a/src/helpers/FairnessLimiter.h b/src/helpers/FairnessLimiter.h index f15cd22f..adf65d07 100644 --- a/src/helpers/FairnessLimiter.h +++ b/src/helpers/FairnessLimiter.h @@ -70,7 +70,9 @@ * nothing" reduction in wasteful repeats, freeing airtime for useful repeats. */ class FairnessLimiter { - // Capacity of when a bucket is full. + // Capacity of when a bucket is full. Runtime-settable (setGroupCap etc.) so + // limits can be loosened over RF admin without a reflash -- 0 to a setter + // resets to the build default below. uint8_t group_cap = FAIRNESS_GROUP_CAP, sender_normal_cap = FAIRNESS_SENDER_NORMAL_CAP, sender_low_cap = FAIRNESS_SENDER_LOW_CAP; @@ -80,6 +82,11 @@ class FairnessLimiter { uint8_t sender_normal_map[SENDER_NORMAL_MAP_SIZE] = {}; uint8_t sender_low_map[SENDER_LOW_MAP_SIZE] = {}; uint8_t group_map[GROUP_MAP_SIZE] = {}; + // Per-bucket deny counters -- the "grid": which hash buckets we are actually + // shedding, so a shed is visible instead of a bare total. Saturating uint16. + uint16_t group_deny[GROUP_MAP_SIZE] = {}; + uint16_t sender_normal_deny[SENDER_NORMAL_MAP_SIZE] = {}; + uint16_t sender_low_deny[SENDER_LOW_MAP_SIZE] = {}; public: FairnessLimiter() {} @@ -104,6 +111,20 @@ public: uint32_t deniedSenderLow() const { return denied_sender_low; } uint32_t deniedGroup() const { return denied_group; } + // Runtime cap tuning (0 = restore the build default for that bucket). + void setGroupCap(uint8_t c) { group_cap = c ? c : FAIRNESS_GROUP_CAP; } + void setSenderNormalCap(uint8_t c) { sender_normal_cap = c ? c : FAIRNESS_SENDER_NORMAL_CAP; } + void setSenderLowCap(uint8_t c) { sender_low_cap = c ? c : FAIRNESS_SENDER_LOW_CAP; } + uint8_t groupCap() const { return group_cap; } + uint8_t senderNormalCap() const { return sender_normal_cap; } + uint8_t senderLowCap() const { return sender_low_cap; } + + // The grid: append "=" for each bucket with denies, per category, + // busiest first, into `out` (bounded by max_len). Returns chars written. + // `pfx` is the low bits of the sender/channel hash -- cross-reference the + // observer feed / CoreScope to map a hot bucket back to an actual node. + int formatGrid(char* out, int max_len) const; + static int sender_normal_idx(const uint8_t* hash) { return hash[0] & SENDER_NORMAL_MASK; } static int sender_low_idx(const uint8_t* hash) { return hash[0] & SENDER_LOW_MASK; } static int group_idx(const uint8_t* hash) { return hash[0] & GROUP_MASK; } diff --git a/test/test_fairness_limiter/test_fairness_limiter.cpp b/test/test_fairness_limiter/test_fairness_limiter.cpp index 3736e205..7f3fd69d 100644 --- a/test/test_fairness_limiter/test_fairness_limiter.cpp +++ b/test/test_fairness_limiter/test_fairness_limiter.cpp @@ -1,4 +1,5 @@ #include +#include #include "helpers/FairnessLimiter.h" using namespace mesh; @@ -141,6 +142,54 @@ TEST(FairnessLimiter, TransportFloodIsLimitedLikeFlood) { EXPECT_EQ(fl.deniedGroup(), 1u); } +// ── runtime cap tuning ─────────────────────────────────────────────────────── + +TEST(FairnessLimiter, SetCapZeroRestoresDefault) { + FairnessLimiter fl; + fl.setGroupCap(5); + EXPECT_EQ(fl.groupCap(), 5); + fl.setGroupCap(0); // 0 = restore build default + EXPECT_EQ(fl.groupCap(), FAIRNESS_GROUP_CAP); +} + +TEST(FairnessLimiter, RaisedSenderCapAllowsBiggerBurst) { + FairnessLimiter fl; + fl.setSenderNormalCap(100); + for (int i = 0; i < 200; i++) fl.refillSenderNormal(); // fill to the raised cap + Packet p = makePacket(ROUTE_TYPE_FLOOD, PAYLOAD_TYPE_TXT_MSG, {0x10, 0x22, 0, 0}); + int allowed = 0; + for (int i = 0; i < 200; i++) if (fl.allowPacket(&p)) allowed++; + EXPECT_EQ(allowed, 100); // the new cap, not the default 30 +} + +// ── grid: which buckets we shed ────────────────────────────────────────────── + +TEST(FairnessLimiter, GridReportsDeniedBuckets) { + FairnessLimiter fl; + fl.refillGroup(); // 1 token per group bucket + // 0xEF -> bucket 0x0F; first passes, then 2 denies on that bucket + Packet g = makePacket(ROUTE_TYPE_FLOOD, PAYLOAD_TYPE_GRP_TXT, {0xEF, 0, 0}); + fl.allowPacket(&g); // consumes the token + fl.allowPacket(&g); // deny 1 + fl.allowPacket(&g); // deny 2 + char grid[180]; + fl.formatGrid(grid, sizeof(grid)); + std::string s(grid); + EXPECT_NE(s.find("group(cap 20):"), std::string::npos); + EXPECT_NE(s.find("0f=2"), std::string::npos); // bucket 0x0f denied twice + EXPECT_NE(s.find("sender(cap 30): -"), std::string::npos); // nothing shed there +} + +TEST(FairnessLimiter, GridIsNonDestructive) { + FairnessLimiter fl; + Packet g = makePacket(ROUTE_TYPE_FLOOD, PAYLOAD_TYPE_GRP_TXT, {0xEF, 0, 0}); + fl.allowPacket(&g); // zero tokens -> deny 1 + char a[180], b[180]; + fl.formatGrid(a, sizeof(a)); + fl.formatGrid(b, sizeof(b)); + EXPECT_STREQ(a, b); // repeated calls give the same picture +} + int main(int argc, char** argv) { ::testing::InitGoogleTest(&argc, argv); return RUN_ALL_TESTS();