feat(ffi): RET_STALE_WARN progress callback replacing handler timeout (#129)

Author: Ivansete-status

CHANGELOG.md

@@ -42,16 +42,17 @@ All notable changes to this project are documented in this file.
   `nimble genbindings_c` / `genbindings_c_echo` / `check_bindings_c` /
   `test_c_e2e` tasks, a `tests/e2e/c` ctest harness, and a
   `tests/unit/test_c_codegen.nim` unit suite.
-- Configurable per-request handler timeout with a finite default: each
-  `FFIContext` now carries a `defaultRequestTimeout` (5s) applied to every
-  handler, replacing the previous unbounded wait so a wedged handler can no
-  longer hang a foreign caller forever. On trip the caller is unblocked with an
-  `ffi request timed out after <n>ms` err; the handler is left running (not
-  cancelled, since a hard-cancel mid-call into the underlying library can leave
-  it partial), and the callback still fires exactly once. Override per proc with
-  a `"timeout = <ms>"` spec (e.g. `{.ffi: "timeout = 30000".}`), parsed like the
-  `abi = ...` spec; runtime-only, codegen ignores it
-  ([#93](https://github.com/logos-messaging/nim-ffi/issues/93)).
+- Non-terminal `RET_STALE_WARN` (3) progress callback in place of a handler
+  timeout: nim-ffi never times a handler out (a hard-cancel mid-call into the
+  underlying library can leave it half-applied). Instead, while a request is
+  still in flight its result callback receives a `RET_STALE_WARN` every 5s
+  (Android's ANR interval; override with `-d:ffiStaleWarnIntervalMs=<ms>`), with
+  the payload carrying the elapsed milliseconds as a decimal string. The request
+  always ends with exactly one terminal `RET_OK` / `RET_ERR`; the dev decides
+  what to do with a slow one. Replaces the never-released per-proc
+  `{.ffi: "timeout = <ms>".}` override and the `defaultRequestTimeout` context
+  field ([#126](https://github.com/logos-messaging/nim-ffi/issues/126),
+  supersedes [#93](https://github.com/logos-messaging/nim-ffi/issues/93)).
 - Per-interaction ABI-format annotations: `declareLibrary` now takes an
   optional `defaultABIFormat` (`"cbor"` default, or `"c"`) that every
   `{.ffi.}` / `{.ffiCtor.}` / `{.ffiDtor.}` / `{.ffiRaw.}` / `{.ffiEvent.}`

README.md

@@ -91,26 +91,33 @@ Every `{.ffi.}` / `{.ffiCtor.}` proc must have an explicit
 `return ok(...)` without awaiting). The `Result`'s error string is delivered to
 the foreign caller as the failure message.
 
-### Request timeouts
-
-Every handler runs under a deadline. The default is `DefaultRequestTimeout`
-(5s, `ffi/ffi_context.nim`), applied to every proc so a wedged handler can't
-hang a foreign caller forever. On trip the caller is unblocked with an `ffi
-request timed out after <n>ms` error; the handler is **not** cancelled — a
-hard cancel mid-call into the underlying library can leave it half-applied — so
-it keeps running, and the caller's callback still fires exactly once.
-
-Raise or lower the deadline per proc with a `"timeout = <ms>"` spec, parsed
-like the `abi = ...` spec below:
-
-```nim
-proc slowOp*(
-    c: Counter, req: BumpRequest
-): Future[Result[BumpResponse, string]] {.ffi: "timeout = 30000".} =
-  ...
-```
-
-The timeout is runtime-only; binding codegen ignores it.
+### The result callback contract
+
+Each request carries a result callback. It receives one of these status codes
+(`ret` / `err_code`):
+
+| Code | Value | Terminal? | Meaning |
+| --- | --- | --- | --- |
+| `RET_OK` | 0 | yes | Success; the payload carries the encoded result. |
+| `RET_ERR` | 1 | yes | Failure; the payload carries the UTF-8 error string. |
+| `RET_MISSING_CALLBACK` | 2 | — | No callback was passed; the request path reports this itself. |
+| `RET_STALE_WARN` | 3 | **no** | Progress ping — the handler is still running. |
+
+**nim-ffi never times a handler out.** A slow request runs to its natural
+`RET_OK` / `RET_ERR`; it is never cancelled (a hard-cancel mid-call into the
+underlying library can leave it half-applied). Instead, while a handler is still
+in flight the callback receives a **non-terminal** `RET_STALE_WARN` every 5s
+(Android's ANR interval; override at build time with
+`-d:ffiStaleWarnIntervalMs=<ms>`), with the payload carrying the elapsed
+milliseconds as a decimal string. The dev decides what to do with a slow request
+— keep waiting, surface a spinner, tear the context down — nim-ffi does not
+decide for them.
+
+`RET_STALE_WARN` may fire any number of times and is **always** followed by
+exactly one terminal `RET_OK` / `RET_ERR`. A caller that only wants the final
+answer must ignore it (do not treat a non-zero code as an error without checking
+for `RET_STALE_WARN` first). The generated higher-level typed wrappers currently
+ignore it; the progress signal is delivered at the raw result-callback boundary.
 
 ### Events
 

examples/echo/c_abi_bindings/echo.h

@@ -9,6 +9,10 @@
 #define NIMFFI_RET_OK 0
 #define NIMFFI_RET_ERR 1
 #define NIMFFI_RET_MISSING_CALLBACK 2
+/* Non-terminal: the request is still running. Fires every ~5s with `msg`
+   carrying the elapsed milliseconds as decimal text; always followed by a
+   terminal RET_OK/RET_ERR. Ignore it unless you want progress. */
+#define NIMFFI_RET_STALE_WARN 3
 
 /* Flat wire structs — the C ABI. Strings are borrowed, NUL-terminated
    `const char*` valid only for the duration of the call they cross. */
@@ -54,6 +58,8 @@ typedef struct { EchoCreateFn fn; void* user_data; } EchoCreateBox;
 static void echo_create_trampoline(int ret, const char* ctx_addr, const char* err_msg, void* ud) {
     EchoCreateBox* box = (EchoCreateBox*)ud;
     if (!box) return;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) { free(box); return; }
     if (ret != 0) {
         box->fn(ret, NULL, err_msg ? err_msg : "FFI create failed", box->user_data);

examples/echo/c_bindings/echo.h

@@ -222,6 +222,8 @@ typedef void (*EchoCreateFn)(int err_code, EchoCtx* ctx, const char* err_msg, vo
 typedef struct { EchoCreateFn fn; void* user_data; } EchoCreateBox;
 static void echo_create_trampoline(int ret, const char* msg, size_t len, void* ud) {
     EchoCreateBox* box = (EchoCreateBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -297,6 +299,8 @@ typedef void (*EchoShoutReplyFn)(int err_code, const ShoutResponse* reply, const
 typedef struct { EchoShoutReplyFn fn; void* user_data; } EchoShoutCallBox;
 static void echo_shout_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     EchoShoutCallBox* box = (EchoShoutCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -357,6 +361,8 @@ typedef void (*EchoVersionReplyFn)(int err_code, const NimFfiStr* reply, const c
 typedef struct { EchoVersionReplyFn fn; void* user_data; } EchoVersionCallBox;
 static void echo_version_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     EchoVersionCallBox* box = (EchoVersionCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;

examples/echo/c_bindings/nim_ffi_cbor.h

@@ -20,10 +20,17 @@ typedef void (*FFICallback)(int ret, const char* msg, size_t len, void* user_dat
  * value handed to a result callback's `err_code` (or returned by a submit call)
  * is a failure. NIMFFI_RET_MISSING_CALLBACK is a special case from the Nim
  * dispatcher: the callback will never fire, so the request path must report the
- * failure itself. */
+ * failure itself.
+ *
+ * NIMFFI_RET_STALE_WARN is the one NON-terminal code: nim-ffi delivers it every
+ * ~5s while a handler is still running (with `msg`/`len` carrying the elapsed
+ * milliseconds as decimal text), then still ends with a terminal RET_OK/RET_ERR.
+ * A caller that only wants the final answer must ignore it, not treat it as an
+ * error. */
 #define NIMFFI_RET_OK 0
 #define NIMFFI_RET_ERROR 1
 #define NIMFFI_RET_MISSING_CALLBACK 2
+#define NIMFFI_RET_STALE_WARN 3
 
 /* ── leaf encoders ─────────────────────────────────────────────────────── */
 static inline CborError nimffi_enc_bool(CborEncoder* e, const bool* v) {

examples/echo/cpp_bindings/echo.hpp

@@ -29,6 +29,16 @@ extern "C" {
 #include <tinycbor/cbor.h>
 }
 
+// nim-ffi result-callback status codes (mirror ffi/ffi_types.nim and the C
+// header). Guarded so a translation unit that also pulls in the C header keeps
+// a single definition.
+#ifndef NIMFFI_RET_OK
+#define NIMFFI_RET_OK 0
+#define NIMFFI_RET_ERR 1
+#define NIMFFI_RET_MISSING_CALLBACK 2
+#define NIMFFI_RET_STALE_WARN 3
+#endif
+
 // ============================================================
 // Result<T> — exception-free error channel
 // ============================================================
@@ -448,14 +458,20 @@ struct FFICallState_ {
 };
 
 inline void ffi_cb_(int ret, const char* msg, size_t len, void* ud) {
+    // NIMFFI_RET_STALE_WARN (3) is a non-terminal progress ping: the request is
+    // still running. This blocking wrapper only reports the final result, so
+    // ignore it WITHOUT touching `ud` — a terminal callback still owns the
+    // shared handle and will free it.
+    if (ret == NIMFFI_RET_STALE_WARN) return;
+
     // ffi_call_ heap-allocated a shared_ptr and passed its address as ud;
     // take ownership here so it's freed on every exit path.
     std::unique_ptr<std::shared_ptr<FFICallState_>> handle(
         static_cast<std::shared_ptr<FFICallState_>*>(ud));
     FFICallState_& s = **handle;
 
     std::lock_guard<std::mutex> lock(s.mtx);
-    s.ok = (ret == 0);
+    s.ok = (ret == NIMFFI_RET_OK);
     if (msg && len > 0) {
         const auto* p = reinterpret_cast<const std::uint8_t*>(msg);
         if (s.ok) s.bytes.assign(p, p + len);
@@ -472,7 +488,7 @@ inline Result<std::vector<std::uint8_t>> ffi_call_(
     auto state = std::make_shared<FFICallState_>();
     auto* cb_ref = new std::shared_ptr<FFICallState_>(state);
     const int ret = f(ffi_cb_, cb_ref);
-    if (ret == 2) {
+    if (ret == NIMFFI_RET_MISSING_CALLBACK) {
         delete cb_ref;
         return Result<Bytes>::err("RET_MISSING_CALLBACK (internal error)");
     }

examples/timer/c_bindings/my_timer.h

@@ -829,6 +829,8 @@ typedef void (*MyTimerCreateFn)(int err_code, MyTimerCtx* ctx, const char* err_m
 typedef struct { MyTimerCreateFn fn; void* user_data; } MyTimerCreateBox;
 static void my_timer_create_trampoline(int ret, const char* msg, size_t len, void* ud) {
     MyTimerCreateBox* box = (MyTimerCreateBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -940,6 +942,8 @@ typedef void (*MyTimerEchoReplyFn)(int err_code, const EchoResponse* reply, cons
 typedef struct { MyTimerEchoReplyFn fn; void* user_data; } MyTimerEchoCallBox;
 static void my_timer_echo_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     MyTimerEchoCallBox* box = (MyTimerEchoCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -1000,6 +1004,8 @@ typedef void (*MyTimerVersionReplyFn)(int err_code, const NimFfiStr* reply, cons
 typedef struct { MyTimerVersionReplyFn fn; void* user_data; } MyTimerVersionCallBox;
 static void my_timer_version_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     MyTimerVersionCallBox* box = (MyTimerVersionCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -1059,6 +1065,8 @@ typedef void (*MyTimerComplexReplyFn)(int err_code, const ComplexResponse* reply
 typedef struct { MyTimerComplexReplyFn fn; void* user_data; } MyTimerComplexCallBox;
 static void my_timer_complex_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     MyTimerComplexCallBox* box = (MyTimerComplexCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;
@@ -1119,6 +1127,8 @@ typedef void (*MyTimerScheduleReplyFn)(int err_code, const ScheduleResult* reply
 typedef struct { MyTimerScheduleReplyFn fn; void* user_data; } MyTimerScheduleCallBox;
 static void my_timer_schedule_reply_trampoline(int ret, const char* msg, size_t len, void* ud) {
     MyTimerScheduleCallBox* box = (MyTimerScheduleCallBox*)ud;
+    /* Non-terminal progress ping: keep the box for the terminal reply. */
+    if (ret == NIMFFI_RET_STALE_WARN) return;
     if (!box->fn) {
         free(box);
         return;

examples/timer/c_bindings/nim_ffi_cbor.h

@@ -20,10 +20,17 @@ typedef void (*FFICallback)(int ret, const char* msg, size_t len, void* user_dat
  * value handed to a result callback's `err_code` (or returned by a submit call)
  * is a failure. NIMFFI_RET_MISSING_CALLBACK is a special case from the Nim
  * dispatcher: the callback will never fire, so the request path must report the
- * failure itself. */
+ * failure itself.
+ *
+ * NIMFFI_RET_STALE_WARN is the one NON-terminal code: nim-ffi delivers it every
+ * ~5s while a handler is still running (with `msg`/`len` carrying the elapsed
+ * milliseconds as decimal text), then still ends with a terminal RET_OK/RET_ERR.
+ * A caller that only wants the final answer must ignore it, not treat it as an
+ * error. */
 #define NIMFFI_RET_OK 0
 #define NIMFFI_RET_ERROR 1
 #define NIMFFI_RET_MISSING_CALLBACK 2
+#define NIMFFI_RET_STALE_WARN 3
 
 /* ── leaf encoders ─────────────────────────────────────────────────────── */
 static inline CborError nimffi_enc_bool(CborEncoder* e, const bool* v) {

examples/timer/cpp_bindings/my_timer.hpp

@@ -29,6 +29,16 @@ extern "C" {
 #include <tinycbor/cbor.h>
 }
 
+// nim-ffi result-callback status codes (mirror ffi/ffi_types.nim and the C
+// header). Guarded so a translation unit that also pulls in the C header keeps
+// a single definition.
+#ifndef NIMFFI_RET_OK
+#define NIMFFI_RET_OK 0
+#define NIMFFI_RET_ERR 1
+#define NIMFFI_RET_MISSING_CALLBACK 2
+#define NIMFFI_RET_STALE_WARN 3
+#endif
+
 #include <unordered_map>
 // ============================================================
 // Result<T> — exception-free error channel
@@ -748,14 +758,20 @@ struct FFICallState_ {
 };
 
 inline void ffi_cb_(int ret, const char* msg, size_t len, void* ud) {
+    // NIMFFI_RET_STALE_WARN (3) is a non-terminal progress ping: the request is
+    // still running. This blocking wrapper only reports the final result, so
+    // ignore it WITHOUT touching `ud` — a terminal callback still owns the
+    // shared handle and will free it.
+    if (ret == NIMFFI_RET_STALE_WARN) return;
+
     // ffi_call_ heap-allocated a shared_ptr and passed its address as ud;
     // take ownership here so it's freed on every exit path.
     std::unique_ptr<std::shared_ptr<FFICallState_>> handle(
         static_cast<std::shared_ptr<FFICallState_>*>(ud));
     FFICallState_& s = **handle;
 
     std::lock_guard<std::mutex> lock(s.mtx);
-    s.ok = (ret == 0);
+    s.ok = (ret == NIMFFI_RET_OK);
     if (msg && len > 0) {
         const auto* p = reinterpret_cast<const std::uint8_t*>(msg);
         if (s.ok) s.bytes.assign(p, p + len);
@@ -772,7 +788,7 @@ inline Result<std::vector<std::uint8_t>> ffi_call_(
     auto state = std::make_shared<FFICallState_>();
     auto* cb_ref = new std::shared_ptr<FFICallState_>(state);
     const int ret = f(ffi_cb_, cb_ref);
-    if (ret == 2) {
+    if (ret == NIMFFI_RET_MISSING_CALLBACK) {
         delete cb_ref;
         return Result<Bytes>::err("RET_MISSING_CALLBACK (internal error)");
     }

examples/timer/rust_bindings/src/api.rs

@@ -31,16 +31,26 @@ unsafe fn ffi_payload(ret: c_int, msg: *const c_char, len: usize) -> FFIResult {
     } else {
         slice::from_raw_parts(msg as *const u8, len).to_vec()
     };
-    if ret == 0 { Ok(bytes) }
+    if ret == NIMFFI_RET_OK { Ok(bytes) }
     else        { Err(String::from_utf8_lossy(&bytes).into_owned()) }
 }
 
+// nim-ffi result-callback status codes (mirror ffi/ffi_types.nim).
+const NIMFFI_RET_OK: c_int = 0;
+const NIMFFI_RET_MISSING_CALLBACK: c_int = 2;
+const NIMFFI_RET_STALE_WARN: c_int = 3;
+
 unsafe extern "C" fn on_result(
     ret: c_int,
     msg: *const c_char,
     len: usize,
     user_data: *mut c_void,
 ) {
+    // NIMFFI_RET_STALE_WARN (3) is a non-terminal progress ping: the request
+    // is still running. This wrapper only delivers the final result, so ignore
+    // it WITHOUT reclaiming the box — a terminal callback still owns the Sender.
+    if ret == NIMFFI_RET_STALE_WARN { return; }
+
     // Take ownership of the boxed Sender — dropping it at end of scope
     // releases the only outstanding handle.
     let tx = Box::from_raw(user_data as *mut FFISender);
@@ -66,7 +76,7 @@ where
     let (tx, rx) = flume::bounded::<FFIResult>(1);
     let raw = Box::into_raw(Box::new(tx)) as *mut c_void;
     let ret = f(on_result, raw);
-    if ret == 2 {
+    if ret == NIMFFI_RET_MISSING_CALLBACK {
         // Callback will never fire; reclaim the box to avoid a leak.
         drop(unsafe { Box::from_raw(raw as *mut FFISender) });
         return Err("RET_MISSING_CALLBACK (internal error)".into());
@@ -87,7 +97,7 @@ where
     let (tx, rx) = flume::bounded::<FFIResult>(1);
     let raw = Box::into_raw(Box::new(tx)) as *mut c_void;
     let ret = f(on_result, raw);
-    if ret == 2 {
+    if ret == NIMFFI_RET_MISSING_CALLBACK {
         drop(unsafe { Box::from_raw(raw as *mut FFISender) });
         return Err("RET_MISSING_CALLBACK (internal error)".into());
     }