feat: heartbeat control (#205)

* chore: gate heartbeat callback
* fix: unit-tests

Author: zfields

.gitignore

@@ -13,3 +13,5 @@ settings.json
 CMakeFiles/
 CMakeCache.txt
 cppcheck_output.txt
+
+.claude/

CMakeLists.txt

@@ -23,6 +23,7 @@ option(NOTE_C_MEM_CHECK "Run tests with Valgrind." OFF)
 option(NOTE_C_NO_LIBC "Build the library without linking against libc, generating errors for any undefined symbols." OFF)
 option(NOTE_C_SHOW_MALLOC "Build the library with flags required to log memory usage." OFF)
 option(NOTE_C_SINGLE_PRECISION "Use single precision for JSON floating point numbers." OFF)
+option(NOTE_C_HEARTBEAT_CALLBACK "Enable heartbeat callback support." OFF)
 
 set(NOTE_C_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 add_library(note_c SHARED)
@@ -120,6 +121,14 @@ if(NOTE_C_SINGLE_PRECISION)
     )
 endif()
 
+if(NOTE_C_HEARTBEAT_CALLBACK)
+    target_compile_definitions(
+        note_c
+        PUBLIC
+            NOTE_C_HEARTBEAT_CALLBACK
+    )
+endif()
+
 if(NOTE_C_BUILD_TESTS)
     # Including CTest here rather than in test/CMakeLists.txt allows us to run
     # ctest from the root build directory (e.g. build/ instead of build/test/).

n_hooks.c

@@ -168,19 +168,21 @@ NOTE_C_STATIC i2cTransmitFn hookI2CTransmit = NULL;
 */
 /**************************************************************************/
 NOTE_C_STATIC i2cReceiveFn hookI2CReceive = NULL;
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 //**************************************************************************/
 /*!
   @brief  Hook for a heartbeat notification
 */
 /**************************************************************************/
 NOTE_C_STATIC heartbeatFn hookHeartbeat = NULL;
 NOTE_C_STATIC void *hookHeartbeatContext = NULL;
+#endif
+#ifndef NOTE_NODEBUG
 //**************************************************************************/
 /*!
   @brief Variable used to determine the runtime logging level
 */
 /**************************************************************************/
-#ifndef NOTE_NODEBUG
 NOTE_C_STATIC int noteLogLevel = NOTE_C_LOG_LEVEL;
 #endif
 
@@ -303,6 +305,7 @@ void NoteSetFn(mallocFn mallocHook, freeFn freeHook, delayMsFn delayMsHook,
     _UnlockNote();
 }
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 //**************************************************************************/
 /*!
   @brief  Set the heartbeat function
@@ -317,6 +320,7 @@ void NoteSetFnHeartbeat(heartbeatFn fn, void *context)
     hookHeartbeatContext = context;
     _UnlockNote();
 }
+#endif
 
 //**************************************************************************/
 /*!
@@ -785,18 +789,22 @@ void NoteUnlockI2C(void)
     }
 }
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 //**************************************************************************/
 /*!
   @brief  Call a heartbeat function if registered
-  @param   heartbeatJson Pointer to null-terminated heartbeat Json string.
+  @param   heartbeatJson Pointer to null-terminated heartbeat JSON string.
+  @returns  `true` if the heartbeat callback wishes to abandon the transaction.
 */
 /**************************************************************************/
-void _noteHeartbeat(const char *heartbeatJson)
+bool _noteHeartbeat(const char *heartbeatJson)
 {
     if (hookHeartbeat != NULL) {
-        hookHeartbeat(heartbeatJson, hookHeartbeatContext);
+        return hookHeartbeat(heartbeatJson, hookHeartbeatContext);
     }
+    return false;
 }
+#endif
 
 //**************************************************************************/
 /*!
@@ -858,6 +866,7 @@ void NoteGetFnDebugOutput(debugOutputFn *fn)
     }
 }
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 /*!
  @brief Get the user-defined heartbeat function.
  @param fn Pointer to store the heartbeat function pointer.
@@ -872,6 +881,7 @@ void NoteGetFnHeartbeat(heartbeatFn *fn, void **context)
         *context = hookHeartbeatContext;
     }
 }
+#endif
 
 /*!
  @brief Get the platform-specific transaction functions.

n_lib.h

@@ -150,7 +150,9 @@ const char *_noteJSONTransaction(const char *request, size_t reqLen, char **resp
 const char *_noteChunkedReceive(uint8_t *buffer, uint32_t *size, bool delay, uint32_t timeoutMs, uint32_t *available);
 const char *_noteChunkedTransmit(uint8_t *buffer, uint32_t size, bool delay);
 bool _noteIsDebugOutputActive(void);
-void _noteHeartbeat(const char *heartbeatJson);
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
+bool _noteHeartbeat(const char *heartbeatJson);
+#endif
 
 // Utilities
 void _n_htoa32(uint32_t n, char *p);

n_request.c

@@ -801,7 +801,15 @@ J *_noteTransactionShouldLock(J *req, bool lockNotecard)
             _Free(rspJsonStr);
             const char * const status = JGetString(rsp, c_status);
             NOTE_C_LOG_DEBUG(ERRSTR(status, c_heartbeat));
-            _noteHeartbeat(status);
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
+            if (_noteHeartbeat(status)) {
+                errStr = ERRSTR("host abandoned transaction {heartbeat}", c_heartbeat);
+                NoteResetRequired();
+                break;
+            }
+#else
+            (void)status; // avoid unused variable warning when NOTE_C_LOW_MEM defined
+#endif
             --lastRequestRetries; // Heartbeats do not count against retry limit
             continue;
         } else if (isIoError || isBadBin) {

note.h

@@ -142,15 +142,19 @@ typedef uint32_t (*getMsFn) (void);
 
 typedef size_t (*debugOutputFn) (const char *text);
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 /*!
  @typedef heartbeatFn
 
  @brief The type for a heartbeat notification
 
  @param heartbeatJson The heartbeat status received
  @param context User context passed to the heartbeat function
+
+ @returns `true` if the heartbeat processing should abandon the transaction.
  */
-typedef void (*heartbeatFn) (const char *heartbeatJson, void *context);
+typedef bool (*heartbeatFn) (const char *heartbeatJson, void *context);
+#endif
 
 /*!
  @typedef i2cReceiveFn
@@ -302,8 +306,10 @@ bool NoteErrorContains(const char *errstr, const char *errtype);
 void NoteErrorClean(char *errbuf);
 void NoteSetFnDebugOutput(debugOutputFn fn);
 void NoteGetFnDebugOutput(debugOutputFn *fn);
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
 void NoteSetFnHeartbeat(heartbeatFn fn, void *context);
 void NoteGetFnHeartbeat(heartbeatFn *fn, void **context);
+#endif
 void NoteSetFnTransaction(txnStartFn startFn, txnStopFn stopFn);
 void NoteGetFnTransaction(txnStartFn *startFn, txnStopFn *stopFn);
 void NoteSetFnMutex(mutexFn lockI2Cfn, mutexFn unlockI2Cfn, mutexFn lockNotefn,

scripts/run_unit_tests.sh

@@ -1,6 +1,7 @@
 #!/bin/bash
 
 COVERAGE=0
+HEARTBEAT_CALLBACK=0
 MEM_CHECK=0
 LOW_MEM=0
 SHOW_MALLOC=0
@@ -11,6 +12,7 @@ VERBOSE=0
 while [[ "$#" -gt 0 ]]; do
     case $1 in
         --coverage) COVERAGE=1 ;;
+        --heartbeat-callback) HEARTBEAT_CALLBACK=1 ;;
         --low-mem) LOW_MEM=1 ;;
         --mem-check) MEM_CHECK=1 ;;
         --show-malloc) SHOW_MALLOC=1 ;;
@@ -59,6 +61,9 @@ fi
 if [[ $SINGLE_PRECISION -eq 1 ]]; then
     CMAKE_OPTIONS="${CMAKE_OPTIONS} -DNOTE_C_SINGLE_PRECISION:BOOL=ON"
 fi
+if [[ $HEARTBEAT_CALLBACK -eq 1 ]]; then
+    CMAKE_OPTIONS="${CMAKE_OPTIONS} -DNOTE_C_HEARTBEAT_CALLBACK:BOOL=ON"
+fi
 if [[ $VERBOSE -eq 1 ]]; then
     CMAKE_OPTIONS="${CMAKE_OPTIONS} -DCMAKE_VERBOSE_MAKEFILE:BOOL=ON --log-level=VERBOSE"
 fi

test/src/NoteGetFnHeartbeat_test.cpp

@@ -15,15 +15,18 @@
 
 #include "n_lib.h"
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
+
 namespace
 {
 
 static int testContext = 42;
 
-void mockHeartbeatFn(const char *heartbeatJson, void *context)
+bool mockHeartbeatFn(const char *heartbeatJson, void *context)
 {
     (void)heartbeatJson;
     (void)context;
+    return false;
 }
 
 SCENARIO("NoteGetFnHeartbeat")
@@ -39,7 +42,7 @@ SCENARIO("NoteGetFnHeartbeat")
 
         WHEN("NoteGetFnHeartbeat is called with NULL function pointer") {
             void *retrievedContext = nullptr;
-            
+
             THEN("It should not crash and retrieve context") {
                 NoteGetFnHeartbeat(NULL, &retrievedContext);
                 REQUIRE(retrievedContext == &testContext);
@@ -48,7 +51,7 @@ SCENARIO("NoteGetFnHeartbeat")
 
         WHEN("NoteGetFnHeartbeat is called with NULL context pointer") {
             heartbeatFn retrievedFn = nullptr;
-            
+
             THEN("It should not crash and retrieve function") {
                 NoteGetFnHeartbeat(&retrievedFn, NULL);
                 REQUIRE(retrievedFn == mockHeartbeatFn);
@@ -83,4 +86,6 @@ SCENARIO("NoteGetFnHeartbeat")
     }
 }
 
-}
+}
+
+#endif // NOTE_C_HEARTBEAT_CALLBACK

test/src/NoteSetFnHeartbeat_test.cpp

@@ -16,6 +16,8 @@
 
 #include "n_lib.h"
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
+
 DEFINE_FFF_GLOBALS
 FAKE_VOID_FUNC(_noteLockNote)
 FAKE_VOID_FUNC(_noteUnlockNote)
@@ -30,10 +32,11 @@ static int testContext = 42;
 static const char *lastHeartbeat = nullptr;
 static void *lastContext = nullptr;
 
-void mockHeartbeatFn(const char *heartbeatJson, void *context)
+bool mockHeartbeatFn(const char *heartbeatJson, void *context)
 {
     lastHeartbeat = heartbeatJson;
     lastContext = context;
+    return false;
 }
 
 SCENARIO("NoteSetFnHeartbeat")
@@ -99,4 +102,6 @@ SCENARIO("NoteSetFnHeartbeat")
     RESET_FAKE(_noteUnlockNote);
 }
 
-}
+}
+
+#endif // NOTE_C_HEARTBEAT_CALLBACK

test/src/NoteTransaction_test.cpp

@@ -833,16 +833,18 @@ SCENARIO("NoteTransaction")
         JDelete(resp);
     }
 
+#ifdef NOTE_C_HEARTBEAT_CALLBACK
     SECTION("Heartbeat callback integration - callback invoked on heartbeat response") {
         static char receivedHeartbeat[sizeof("testing stsafe")];
         static void *receivedContext = nullptr;
         static int callbackCount = 0;
         static int testContext = 42;
 
-        auto heartbeatCallback = [](const char *heartbeatJson, void *context) {
+        auto heartbeatCallback = [](const char *heartbeatJson, void *context) -> bool {
             strlcpy(receivedHeartbeat, heartbeatJson, sizeof(receivedHeartbeat));
             receivedContext = context;
             callbackCount++;
+            return false; // Continue processing
         };
 
         // Reset callback state
@@ -882,11 +884,12 @@ SCENARIO("NoteTransaction")
         static int callbackCount = 0;
         static int testContext = 99;
 
-        auto heartbeatCallback = [](const char *heartbeatJson, void *context) {
+        auto heartbeatCallback = [](const char *heartbeatJson, void *context) -> bool {
             strlcpy(lastReceivedHeartbeat, heartbeatJson, sizeof(lastReceivedHeartbeat));
 
             lastReceivedContext = context;
             callbackCount++;
+            return false; // Continue processing
         };
 
         // Reset callback state
@@ -945,10 +948,11 @@ SCENARIO("NoteTransaction")
         static void *receivedContext = reinterpret_cast<void*>(0xDEADBEEF); // Non-null sentinel
         static int callbackCount = 0;
 
-        auto heartbeatCallback = [](const char *heartbeatJson, void *context) {
+        auto heartbeatCallback = [](const char *heartbeatJson, void *context) -> bool {
             strlcpy(receivedHeartbeat, heartbeatJson, sizeof(receivedHeartbeat));
             receivedContext = context;
             callbackCount++;
+            return false; // Continue processing
         };
 
         // Reset callback state
@@ -981,6 +985,7 @@ SCENARIO("NoteTransaction")
         JDelete(req);
         JDelete(resp);
     }
+#endif // NOTE_C_HEARTBEAT_CALLBACK
 
     RESET_FAKE(_crcAdd);
     RESET_FAKE(_crcError);