feat(libxce-failover): endpoint rotator — hint-first target selection + master rotation; keep api_ctx_t decls private (task 2.2)

src/lib/client_internal.h

@@ -2,6 +2,7 @@
 
 #define _CLIENT_INTERNAL_H_ 1
 
+#include <stddef.h>
 #include <stdint.h>
 
 #include "client.h"
@@ -60,4 +61,23 @@ typedef struct {
     xce_failover_state_t failover;
 } api_ctx_t;
 
+/*
+ * EndpointRotator (task 2.2) — these operate on the private api_ctx_t, so they
+ * live in this internal header rather than the public xce/client_failover.h.
+ *
+ * xce_failover_next_target(): PURE target-selection (no I/O). If a redirect-
+ * address hint is set on ac->ctx, write it out and CONSUME it (one-shot,
+ * advisory). Otherwise advance the sticky master cursor (ac->failover.cur_master)
+ * to the next configured master in ac->conf, wrapping around. Returns 0,
+ * -EINVAL on a NULL/zero argument, or -ENOENT if no masters and no hint.
+ * Correctness never depends on the hint.
+ *
+ * xce_failover_rotate(): close the stale connection on ac->ep and reconnect the
+ * SAME endpoint object to the chosen target. Thin wrapper over the selector +
+ * endpoint_connect(); the live socket path is exercised by the E2E task.
+ */
+int xce_failover_next_target(api_ctx_t* ac, char* host_out, size_t host_sz,
+                             uint16_t* port_out);
+int xce_failover_rotate(api_ctx_t* ac);
+
 #endif