onlyn00bs-badge

encounters.h (10137B)

---

 #pragma once
 #include <Arduino.h>
 #include <LittleFS.h>
 #include <string.h>
 #include "config.h"
 
 // ─────────────────────────────────────────────────────────────────────────
 //  Encounter log + report aggregation (your "social graph of the con").
 //
 //  An *encounter* is one continuous stretch you were near a friend. When a
 //  peer ages out of the table (leaves range), one record is appended to
 //  LittleFS. The report aggregates the whole log into per-friend stats.
 //
 //  Privacy by construction: only HMAC-verified crew beacons ever reach the
 //  peer table, so the log can only ever contain your own group — never randos.
 //
 //  Wire format (tab-separated; a sanitized handle can't contain TAB/newline):
 //     first_epoch <TAB> last_epoch <TAB> sightings <TAB> rssi_max <TAB> handle\n
 // ─────────────────────────────────────────────────────────────────────────
 
 #define ENC_LOG_PATH        "/encounters.log"
 #define ENC_LOG_TMP         "/encounters.tmp"   // scratch for drop-oldest compaction
 #define MAX_REPORT_FRIENDS  48
 
 struct Encounter {
   char     handle[HANDLE_MAX_LEN + 1];
   uint32_t first_epoch;
   uint32_t last_epoch;
   uint16_t sightings;
   int8_t   rssi_max;
 };
 
 struct FriendStat {
   char     handle[HANDLE_MAX_LEN + 1];
   uint16_t encounters;
   uint32_t total_seconds;
   int8_t   rssi_max;
   uint32_t first_epoch;
   uint32_t last_epoch;
 };
 
 struct Report {
   int        unique;
   int        total_encounters;
   uint32_t   total_seconds;
   bool       time_synced;
   FriendStat friends[MAX_REPORT_FRIENDS];
   int        n;
 };
 
 // Defined below; both are used by enc_append, which sits above them for readability.
 inline size_t enc_trim_oldest(size_t keep_bytes);
 inline size_t enc_size();
 
 inline bool enc_begin() {
   bool ok = LittleFS.begin(true);   // format on first mount
   // A power cut during a trim leaves ENC_LOG_TMP behind, and nothing else ever cleans it up —
   // it would just sit there consuming space the next trim needs. Boot is the safe moment: no
   // trim can be in flight.
   if (ok) LittleFS.remove(ENC_LOG_TMP);
   return ok;
 }
 
 inline void enc_append(const Encounter& e) {
   File f = LittleFS.open(ENC_LOG_PATH, FILE_APPEND);
   if (!f) return;
   f.printf("%u\t%u\t%u\t%d\t%s\n",
            (unsigned)e.first_epoch, (unsigned)e.last_epoch,
            (unsigned)e.sightings, (int)e.rssi_max, e.handle);
   f.close();                                  // close BEFORE measuring: a File opened for
                                               //   append re-stats the path, which can't see
                                               //   still-buffered bytes.
   // Proactive cap. Keeping the log bounded here — with hundreds of KB free — is what
   // makes the trim always feasible. Left to the 90%-full disk guard instead, the copy has
   // nowhere to go and silently keeps the WRONG end of the log.
   if (enc_size() > ENC_LOG_MAX_BYTES) enc_trim_oldest(ENC_LOG_TRIM_BYTES);
 }
 
 inline void enc_clear() { LittleFS.remove(ENC_LOG_PATH); }
 
 // Current on-disk size of the log (bytes); 0 if absent.
 inline size_t enc_size() {
   File f = LittleFS.open(ENC_LOG_PATH, FILE_READ);
   if (!f) return 0;
   size_t s = f.size();
   f.close();
   return s;
 }
 
 // Drop the OLDEST records so the log keeps only (about) the newest `keep_bytes` — the
 // disk guard's "drop-oldest cap" (bounds the log without ever stopping recording). Records
 // are appended chronologically, so the newest live at the tail: we keep the tail. Streaming
 // LittleFS→LittleFS copy (never slurps the file into RAM), cut aligned to the next record
 // boundary so no half-line survives. Returns bytes freed (0 = no-op / nothing to keep).
 inline size_t enc_trim_oldest(size_t keep_bytes) {
   // The tmp copy coexists with the original until the rename, so the tail we preserve has to
   // fit in the space that is ACTUALLY free — not in whatever the caller hoped for. Asking for
   // more than fits is how this silently kept the oldest slice instead of the newest.
   // Clamping degrades gracefully: worst case we keep less recent history than requested, but
   // it is always the most recent history.
   size_t total = LittleFS.totalBytes(), used = LittleFS.usedBytes();
   size_t room  = (total > used) ? total - used : 0;
   room = (room > ENC_TRIM_FREE_MARGIN) ? room - ENC_TRIM_FREE_MARGIN : 0;
   if (room == 0) return 0;                        // no working space — leave the log intact
   if (keep_bytes > room) keep_bytes = room;
 
   File f = LittleFS.open(ENC_LOG_PATH, FILE_READ);
   if (!f) return 0;
   size_t sz = f.size();
   if (sz <= keep_bytes) { f.close(); return 0; }
   f.seek(sz - keep_bytes);                        // jump to ~keep_bytes before EOF
   while (f.available() && f.read() != '\n') { }   // advance past the partial first line
   if (!f.available()) { f.close(); return 0; }    // nothing whole left after the cut — leave as-is
   File t = LittleFS.open(ENC_LOG_TMP, FILE_WRITE);
   if (!t) { f.close(); return 0; }
   uint8_t buf[256];
   bool ok = true;
   while (f.available()) {
     size_t n = f.read(buf, sizeof(buf));
     if (!n) break;
     if (t.write(buf, n) != n) { ok = false; break; }   // ENOSPC/IO — an unchecked write here
   }                                                    //   once silently lost the newest history
   size_t newsz = t.size();
   t.close();
   f.close();
   // Anything short of a complete copy: throw the partial away and leave the live log alone.
   // A truncated log is worse than an oversized one — it's the con souvenir.
   if (!ok || newsz == 0) { LittleFS.remove(ENC_LOG_TMP); return 0; }
 
   // Replace by rename, WITHOUT removing the live log first: littlefs replaces the destination
   // as part of the rename, so there is no window where neither file exists. The old
   // remove-then-rename could lose the ENTIRE log to a battery cut and orphan the tmp.
   // Fallback kept because overwrite-on-rename wasn't verifiable on this bench (the VFS ships
   // precompiled) — if it refuses, we do it the old way rather than not trim at all.
   if (!LittleFS.rename(ENC_LOG_TMP, ENC_LOG_PATH)) {
     LittleFS.remove(ENC_LOG_PATH);
     if (!LittleFS.rename(ENC_LOG_TMP, ENC_LOG_PATH)) { LittleFS.remove(ENC_LOG_TMP); return 0; }
   }
   return (sz > newsz) ? (sz - newsz) : 0;
 }
 
 // Fold one tab-separated record into the aggregate. `line` is NUL-terminated and is modified
 // in place (tabs become NULs). Malformed lines are dropped, as before.
 inline void enc_report_line(Report* r, char* line) {
   char* save = nullptr;
   char* c_first = strtok_r(line, "\t", &save);
   char* c_last  = strtok_r(nullptr, "\t", &save);
   char* c_sght  = strtok_r(nullptr, "\t", &save);
   char* c_rssi  = strtok_r(nullptr, "\t", &save);
   char* h       = strtok_r(nullptr, "\t", &save);
   if (!c_first || !c_last || !c_sght || !c_rssi || !h) return;
   (void)c_sght;                                    // sightings parsed but unused, as before
 
   uint32_t first = (uint32_t)strtoul(c_first, nullptr, 10);
   uint32_t last  = (uint32_t)strtoul(c_last,  nullptr, 10);
   int8_t   rssi  = (int8_t)strtol(c_rssi,     nullptr, 10);
 
   while (*h == ' ') h++;                           // trim, matching the old String::trim()
   for (int i = (int)strlen(h) - 1; i >= 0 && (h[i] == ' ' || h[i] == '\r'); i--) h[i] = '\0';
   if (!*h) return;
 
   int idx = -1;
   for (int i = 0; i < r->n; i++)
     if (strcmp(h, r->friends[i].handle) == 0) { idx = i; break; }
   if (idx < 0) {
     if (r->n >= MAX_REPORT_FRIENDS) return;
     idx = r->n++;
     FriendStat& nf = r->friends[idx];
     strncpy(nf.handle, h, HANDLE_MAX_LEN);
     nf.handle[HANDLE_MAX_LEN] = '\0';
     nf.rssi_max     = -127;
     nf.first_epoch  = first;
     nf.last_epoch   = last;
   }
 
   FriendStat& fs = r->friends[idx];
   fs.encounters++;
   if (last > first) fs.total_seconds += (last - first);
   if (rssi > fs.rssi_max)       fs.rssi_max    = rssi;
   if (first < fs.first_epoch)   fs.first_epoch = first;
   if (last  > fs.last_epoch)    fs.last_epoch  = last;
 
   r->total_encounters++;
   if (last > first) r->total_seconds += (last - first);
 }
 
 // Read the whole log and aggregate into per-friend stats.
 //
 // Block reads + a fixed line buffer, deliberately — NOT String/readStringUntil. That combo is
 // one buffered fread PER BYTE plus a String::concat per byte, plus five substring temporaries
 // per record; a 10-digit epoch sits exactly at the SSO boundary so both epochs heap-allocate.
 // ~6-7 malloc/free per record turned entering REPORT — an ordinary double-tap — into a
 // multi-second freeze on a large log. This version allocates nothing.
 inline void enc_report(Report* r, bool time_synced) {
   memset(r, 0, sizeof(*r));
   r->time_synced = time_synced;
 
   File f = LittleFS.open(ENC_LOG_PATH, FILE_READ);
   if (!f) return;
 
   uint8_t blk[256];
   char    line[96];                 // a record is ~44 B; 96 is slack, not a limit in practice
   size_t  ll = 0;
   bool    overlong = false;         // line outgrew the buffer → drop it, resync at the next \n
 
   for (;;) {
     int n = f.read(blk, sizeof(blk));
     if (n <= 0) break;
     for (int i = 0; i < n; i++) {
       char c = (char)blk[i];
       if (c != '\n') {
         if (ll < sizeof(line) - 1) line[ll++] = c;
         else                       overlong = true;
         continue;
       }
       if (!overlong && ll) { line[ll] = '\0'; enc_report_line(r, line); }
       ll = 0; overlong = false;
     }
   }
   if (!overlong && ll) { line[ll] = '\0'; enc_report_line(r, line); }   // last line, no \n
   f.close();
 
   // Sort friends by time-together, descending (your most-seen crew first).
   for (int i = 1; i < r->n; i++) {
     FriendStat key = r->friends[i];
     int j = i - 1;
     while (j >= 0 && r->friends[j].total_seconds < key.total_seconds) {
       r->friends[j + 1] = r->friends[j];
       j--;
     }
     r->friends[j + 1] = key;
   }
   r->unique = r->n;
 }