feat(libxce-failover): reconnect/rejoin hook — public setter + post-reconnect invocation before resume (task 4.1)

src/lib/client_internal.h

@@ -30,13 +30,10 @@ typedef enum {
 } api_ctx_state_t;
 
 /*
- * xcecli_reconnect_cb: consumer rejoin hook invoked after a transparent
- * reconnect/failover and before the in-flight request resumes. NULL for pure
- * clients (e.g. xce_test). The public declaration and the
- * xcecli_set_reconnect_handler() setter are introduced by a later task; this
- * private typedef lets the failover state carry the hook now.
+ * xcecli_reconnect_cb (consumer rejoin hook) and its public setter
+ * xcecli_set_reconnect_handler() are declared in the public client.h (included
+ * above) as of task 4.1. The failover state below carries the registered hook.
  */
-typedef int (*xcecli_reconnect_cb)(xcecli_ctx_t c, void* arg);
 
 /*
  * xce_failover_state_t: per-context failover state. Persists across calls so a
@@ -160,4 +157,22 @@ bool xcecli_retry_next(api_ctx_t* ac, int* rc, bool is_write,
  */
 int xcecli_ctx_recover(api_ctx_t* ac);
 
+/*
+ * xcecli_invoke_rejoin (task 4.1) — invoke the consumer rejoin hook once after a
+ * successful reconnect/recovery and BEFORE the interrupted op resumes. Socket-
+ * free (it only calls the stored callback), so it is unit-testable. The
+ * xcecli_retry_next wrapper calls it AFTER xce_failover_rotate +
+ * xcecli_ctx_recover and BEFORE re-sending the op.
+ *
+ * If no hook is registered (rejoin_cb == NULL, a pure client) it is a no-op and
+ * returns 0 so the loop resumes directly. Otherwise it returns the callback's
+ * rc: 0 to proceed, <0 to treat the rejoin as FAILED (the new primary rejected
+ * the daemon's join) — the wrapper then does NOT resume but rotates/backs off on
+ * the next iteration.
+ *
+ * Returns 0 on a successful (or absent) rejoin, the hook's <0 rc on a failed
+ * rejoin, or -EINVAL on a NULL ac.
+ */
+int xcecli_invoke_rejoin(api_ctx_t* ac);
+
 #endif