feat(repeater): fairness grid viditelnost + runtime cap/refill tuning

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Fable 5 committed 2026-09-05 23:39:04 +02:00
1 parent 6f90c80dcc
commit 33af8ecc05
6 files changed
+231 -27

No files matched your search

+89 -24
View File
@@ -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 <group> <sender> <advert>` -- burst caps, 0 = default.
// `fairness refill <group_s> <sender_s> <advert_s>` -- 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 <group> <sender> <advert> (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 <group_s> <sender_s> <advert_s> (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)) {
+12 -2
View File
@@ -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);
+9
View File
@@ -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) { }
+50
View File
@@ -1,6 +1,8 @@
#include "FairnessLimiter.h"
#include <MeshCore.h>
#include <cstdio>
#include <cstring>
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;
}
+22 -1
View File
@@ -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 "<pfx>=<count>" 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; }
@@ -1,4 +1,5 @@
#include <gtest/gtest.h>
#include <string>
#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();