transferLeadership

Initiates a graceful leadership transfer to target per Raft §3.10, and suspends until the transfer is confirmed or fails. It returns normally only when this node observes a leader-authored message from target — an AppendEntries/InstallSnapshot sent by target at a term above the transfer's start term — proof the target actually won an election. An intervening step-down does not resolve the call (the sender of the first higher-term message identifies neither the winner nor even a campaigner): the transfer stays pending until the confirmation arrives or the one-election-timeout auto-abandon fires. Failure still means only that the transfer could not be confirmed within the window: on a degraded/partitioned network the target may have won without its first leader message reaching this node in time.

Protocol:

1. The leader stops accepting new propose and changeMembership calls (they receive NotLeaderException).

2. The leader sends AppendEntries to bring target's log fully up to the leader's last log index (§3.10 step 2 — not merely the current commitIndex, so an uncommitted tail cannot trigger a premature transfer to a not-caught-up target).

3. The leader sends a TimeoutNow message to target.

4. target immediately starts a real election (bypassing its election-timeout wait).

5. If target wins, the old leader steps down on seeing the higher term, and this call returns normally once target's first leader-authored message (typically its initial heartbeat) reaches this node.

6. If that confirmation does not arrive within one election-timeout window, the auto-timeout fires: the node resumes normal operation (accepting proposals again if still leader) and this call throws LeadershipTransferException. The same exception is thrown if this node is re-elected leader itself before the confirmation arrives.

Cancellation: call cancelTransfer from a separate coroutine to abort early. The LeadershipTransferException will carry "cancelled" in its message.

Constraints:

• Only the leader may call this. Non-leaders throw NotLeaderException immediately.

• target must be a voter in the current cluster config, and must not be this node's own id. Invalid targets throw IllegalArgumentException immediately.

• While a transfer is in flight, propose and changeMembership throw NotLeaderException.

Parameters

Throws