handoff.h File Reference

Go to the source code of this file.

Data Structures
struct	consensus_handoff_message_t
struct	consensus_handoff_peer_t
	consensus handoff message is intentionally a small, concrete record. Fields such as kind, generation, sequence, upload_kbps give callers the identity and current value they need. It is normally borrowed from, or owned by, the surrounding subsystem—not independently managed. More...
struct	consensus_handoff_t

Macros
#define	CONSENSUS_HANDOFF_PACKET   6090
#define	CONSENSUS_HANDOFF_VERSION   1
#define	CONSENSUS_HANDOFF_HEADER   64
#define	CONSENSUS_HANDOFF_PROBE_BYTES   65536
#define	CONSENSUS_HANDOFF_FRESH_MS   15000
#define	CONSENSUS_HANDOFF_PREPARE_MS   5000
#define	CONSENSUS_HANDOFF_RECOVERY_MS   15000

Enumerations
enum	consensus_handoff_kind_t {   HANDOFF_SAMPLE_START = 1 , HANDOFF_SAMPLE_DATA , HANDOFF_PREPARE , HANDOFF_READY ,   HANDOFF_PLAN , HANDOFF_COMMIT , HANDOFF_REJECT , HANDOFF_FAILED ,   HANDOFF_SAMPLE_ACK }

Functions
asciichat_error_t	consensus_handoff_decode (const void *data, size_t length, consensus_handoff_message_t *out)
void	consensus_handoff_encode (const consensus_handoff_message_t *message, uint8_t out[64])
void	consensus_handoff_init (consensus_handoff_t *state, const uint8_t session[SESSION_ID_SIZE], const uint8_t host[SESSION_ID_SIZE])
asciichat_error_t	consensus_handoff_join (consensus_handoff_t *state, const uint8_t id[SESSION_ID_SIZE])
void	consensus_handoff_leave (consensus_handoff_t *state, const uint8_t id[SESSION_ID_SIZE])
asciichat_error_t	consensus_handoff_receive (consensus_handoff_t *state, const consensus_handoff_message_t *message, size_t length, uint64_t now_ms)
	Accept a member's probe or preparation reply using receiver-clock time. Probe metadata becomes eligible only with a matched, timely body. Preparation replies must match the current generation, round, and selected successor.
bool	consensus_handoff_tick (consensus_handoff_t *state, uint64_t now_ms, consensus_handoff_message_t *action)
	Advance measured successor selection and bounded host-loss recovery. Fresh eligible peers prepare within five seconds; all recovery attempts share one 15-second budget. Only a fresh prepared peer can commit, and failure is terminal.
void	consensus_handoff_host_lost (consensus_handoff_t *state, const uint8_t host[SESSION_ID_SIZE])
	Record loss of the incumbent, ignoring delayed reports about old hosts. The caller authenticates the reporter before the next tick starts recovery.

Macro Definition Documentation

CONSENSUS_HANDOFF_FRESH_MS

#define CONSENSUS_HANDOFF_FRESH_MS   15000

Definition at line 13 of file handoff.h.

Referenced by consensus_handoff_tick().

CONSENSUS_HANDOFF_HEADER

#define CONSENSUS_HANDOFF_HEADER   64

Definition at line 11 of file handoff.h.

Referenced by acds_main(), consensus_handoff_decode(), consensus_handoff_encode(), consensus_handoff_encode(), and consensus_handoff_receive().

CONSENSUS_HANDOFF_PACKET

#define CONSENSUS_HANDOFF_PACKET   6090

Definition at line 9 of file handoff.h.

Referenced by acip_handle_acds_packet().

CONSENSUS_HANDOFF_PREPARE_MS

#define CONSENSUS_HANDOFF_PREPARE_MS   5000

Definition at line 14 of file handoff.h.

Referenced by consensus_handoff_tick().

CONSENSUS_HANDOFF_PROBE_BYTES

#define CONSENSUS_HANDOFF_PROBE_BYTES   65536

Definition at line 12 of file handoff.h.

Referenced by acds_main(), consensus_handoff_decode(), and consensus_handoff_receive().

CONSENSUS_HANDOFF_RECOVERY_MS

#define CONSENSUS_HANDOFF_RECOVERY_MS   15000

Definition at line 15 of file handoff.h.

Referenced by consensus_handoff_tick().

CONSENSUS_HANDOFF_VERSION

#define CONSENSUS_HANDOFF_VERSION   1

Definition at line 10 of file handoff.h.

Referenced by consensus_handoff_decode(), and consensus_handoff_encode().

Enumeration Type Documentation

consensus_handoff_kind_t

enum consensus_handoff_kind_t

Enumerator
HANDOFF_SAMPLE_START
HANDOFF_SAMPLE_DATA
HANDOFF_PREPARE
HANDOFF_READY
HANDOFF_PLAN
HANDOFF_COMMIT
HANDOFF_REJECT
HANDOFF_FAILED
HANDOFF_SAMPLE_ACK

Definition at line 17 of file handoff.h.

             {
  HANDOFF_SAMPLE_START = 1,
  HANDOFF_SAMPLE_DATA,
  HANDOFF_PREPARE,
  HANDOFF_READY,
  HANDOFF_PLAN,
  HANDOFF_COMMIT,
  HANDOFF_REJECT,
  HANDOFF_FAILED,
  HANDOFF_SAMPLE_ACK
} consensus_handoff_kind_t;

Function Documentation

consensus_handoff_decode()

asciichat_error_t consensus_handoff_decode	(	const void *	data,
		size_t	length,
		consensus_handoff_message_t *	out )

Definition at line 16 of file handoff.c.

                                                                                                            {
  if (!data || !m || length < CONSENSUS_HANDOFF_HEADER)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Truncated handoff frame");
  const uint8_t *p = data;
  if (p[0] != CONSENSUS_HANDOFF_VERSION || p[1] < HANDOFF_SAMPLE_START || p[1] > HANDOFF_SAMPLE_ACK ||
      (p[1] == HANDOFF_SAMPLE_DATA ? length != CONSENSUS_HANDOFF_HEADER + CONSENSUS_HANDOFF_PROBE_BYTES
                                   : length != CONSENSUS_HANDOFF_HEADER))
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid handoff version, kind or length");
  memset(m, 0, sizeof(*m));
  m->kind = p[1];
  memcpy(m->session, p + 4, SESSION_ID_SIZE);
  memcpy(m->participant, p + 20, SESSION_ID_SIZE);
  m->generation = read32(p + 36);
  m->sequence = read32(p + 40);
  m->upload_kbps = read32(p + 44);
  m->rtt_ms = read32(p + 48);
  m->capabilities = p[52];
  m->nat_tier = p[53];
  m->port = (uint16_t)((p[54] << 8) | p[55]);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_handoff_message_t::capabilities, CONSENSUS_HANDOFF_HEADER, CONSENSUS_HANDOFF_PROBE_BYTES, CONSENSUS_HANDOFF_VERSION, ERROR_INVALID_PARAM, ERROR_NETWORK_PROTOCOL, consensus_handoff_message_t::generation, HANDOFF_SAMPLE_ACK, HANDOFF_SAMPLE_DATA, HANDOFF_SAMPLE_START, consensus_handoff_message_t::kind, consensus_handoff_message_t::nat_tier, consensus_handoff_message_t::participant, consensus_handoff_message_t::port, consensus_handoff_message_t::rtt_ms, consensus_handoff_message_t::sequence, consensus_handoff_message_t::session, SESSION_ID_SIZE, SET_ERRNO, and consensus_handoff_message_t::upload_kbps.

consensus_handoff_encode()

void consensus_handoff_encode	(	const consensus_handoff_message_t *	message,
		uint8_t	out[64] )

References action, CONSENSUS_HANDOFF_HEADER, out, and SESSION_ID_SIZE.

consensus_handoff_host_lost()

void consensus_handoff_host_lost	(	consensus_handoff_t *	state,
		const uint8_t	host[SESSION_ID_SIZE] )

Record loss of the incumbent, ignoring delayed reports about old hosts. The caller authenticates the reporter before the next tick starts recovery.

Definition at line 105 of file handoff.c.

                                                                                              {
  if (!memcmp(s->host, host, sizeof(s->host)))
    s->host_lost = true;
}

References consensus_handoff_t::host, consensus_handoff_t::host_lost, and SESSION_ID_SIZE.

consensus_handoff_init()

void consensus_handoff_init	(	consensus_handoff_t *	state,
		const uint8_t	session[SESSION_ID_SIZE],
		const uint8_t	host[SESSION_ID_SIZE] )

Definition at line 52 of file handoff.c.

                                                                 {
  memset(s, 0, sizeof(*s));
  memcpy(s->session, session, SESSION_ID_SIZE);
  memcpy(s->host, host, SESSION_ID_SIZE);
  s->generation = 1;
}

References consensus_handoff_t::generation, consensus_handoff_t::host, consensus_handoff_t::session, and SESSION_ID_SIZE.

consensus_handoff_join()

asciichat_error_t consensus_handoff_join	(	consensus_handoff_t *	state,
		const uint8_t	id[SESSION_ID_SIZE] )

Definition at line 65 of file handoff.c.

                                                                                                    {
  if (find_peer(s, id))
    return ASCIICHAT_OK;
  if (s->count == MAX_SESSION_PARTICIPANTS)
    return SET_ERRNO(ERROR_INVALID_STATE, "Handoff membership full");
  consensus_handoff_peer_t *p = &s->peers[s->count++];
  memset(p, 0, sizeof(*p));
  memcpy(p->id, id, SESSION_ID_SIZE);
  p->nat_tier = 255;
  ++s->generation;
  s->ready = false;
  memset(s->successor, 0, SESSION_ID_SIZE);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_handoff_t::count, ERROR_INVALID_STATE, consensus_handoff_t::generation, consensus_handoff_peer_t::id, MAX_SESSION_PARTICIPANTS, consensus_handoff_peer_t::nat_tier, consensus_handoff_t::peers, consensus_handoff_t::ready, SESSION_ID_SIZE, SET_ERRNO, and consensus_handoff_t::successor.

consensus_handoff_leave()

void consensus_handoff_leave	(	consensus_handoff_t *	state,
		const uint8_t	id[SESSION_ID_SIZE] )

Definition at line 79 of file handoff.c.

                                                                                        {
  // The incumbent can leave before its first measurement creates a peer entry.
  if (memcmp(s->host, id, SESSION_ID_SIZE) == 0)
    s->host_lost = true;
  for (size_t i = 0; i < s->count; ++i) {
    if (memcmp(s->peers[i].id, id, SESSION_ID_SIZE) != 0)
      continue;
    memmove(&s->peers[i], &s->peers[i + 1], (s->count - i - 1) * sizeof(s->peers[0]));
    --s->count;
    ++s->generation;
    if (memcmp(s->host, id, SESSION_ID_SIZE) == 0)
      s->host_lost = true;
    // Pending acknowledgements carry the old membership generation. Reissue
    // their preparation instead of rejecting the late reply and exhausting
    // recovery without trying the still-eligible successor again.
    if (!s->ready || memcmp(s->successor, id, SESSION_ID_SIZE) == 0) {
      memset(s->successor, 0, SESSION_ID_SIZE);
      s->ready = false;
    }
    return;
  }
}

References consensus_handoff_t::count, consensus_handoff_t::generation, consensus_handoff_t::host, consensus_handoff_t::host_lost, consensus_handoff_peer_t::id, consensus_handoff_t::peers, consensus_handoff_t::ready, SESSION_ID_SIZE, and consensus_handoff_t::successor.

consensus_handoff_receive()

asciichat_error_t consensus_handoff_receive	(	consensus_handoff_t *	s,
		const consensus_handoff_message_t *	m,
		size_t	length,
		uint64_t	now )

Accept a member's probe or preparation reply using receiver-clock time. Probe metadata becomes eligible only with a matched, timely body. Preparation replies must match the current generation, round, and selected successor.

Returns

ASCIICHAT_OK if accepted, or a protocol error without accepting the frame.

Definition at line 116 of file handoff.c.

                                                          {
  if (memcmp(s->session, m->session, SESSION_ID_SIZE) != 0)
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Wrong handoff session");
  consensus_handoff_peer_t *p = find_peer(s, m->participant);
  if (!p)
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Handoff sender is not a member");
  if (m->kind == HANDOFF_SAMPLE_START) {
    if (m->sequence <= p->sequence || (p->measured_ms && now - p->measured_ms < 1000))
      return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Repeated or excessive handoff probe");
    p->sequence = m->sequence;
    p->probe_started_ms = now;
    p->measuring = true;
    p->pending_capabilities = m->capabilities & 3;
    p->pending_nat_tier = m->nat_tier <= 4 ? m->nat_tier : 255;
    p->pending_port = m->port;
  } else if (m->kind == HANDOFF_SAMPLE_DATA) {
    if (!p->measuring || m->sequence != p->sequence ||
        length != CONSENSUS_HANDOFF_HEADER + CONSENSUS_HANDOFF_PROBE_BYTES)
      return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Unmatched handoff probe");
    p->measuring = false;
    uint64_t elapsed = now - p->probe_started_ms;
    if (elapsed == 0)
      elapsed = 1;
    p->valid = elapsed <= 5000;
    if (p->valid) {
      p->capabilities = p->pending_capabilities;
      p->nat_tier = p->pending_nat_tier;
      p->port = p->pending_port;
      // A quality refresh cannot extend a failed recovery by retrying the same host.
      if (!s->host_lost)
        p->rejected = false;
    }
    p->upload_kbps = (uint32_t)((uint64_t)CONSENSUS_HANDOFF_PROBE_BYTES * 8 / elapsed);
    p->measured_ms = now;
  } else if (m->kind == HANDOFF_READY || m->kind == HANDOFF_REJECT) {
    if (m->generation != s->generation || m->sequence != s->round ||
        memcmp(m->participant, s->successor, SESSION_ID_SIZE))
      return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Obsolete handoff preparation");
    if (m->kind == HANDOFF_READY && now <= s->prepare_deadline_ms)
      s->ready = true;
    else {
      p->rejected = true;
      s->ready = false;
      memset(s->successor, 0, SESSION_ID_SIZE);
    }
  } else
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Client cannot announce a handoff decision");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_handoff_message_t::capabilities, consensus_handoff_peer_t::capabilities, CONSENSUS_HANDOFF_HEADER, CONSENSUS_HANDOFF_PROBE_BYTES, ERROR_NETWORK_PROTOCOL, consensus_handoff_message_t::generation, consensus_handoff_t::generation, HANDOFF_READY, HANDOFF_REJECT, HANDOFF_SAMPLE_DATA, HANDOFF_SAMPLE_START, consensus_handoff_t::host_lost, consensus_handoff_message_t::kind, consensus_handoff_peer_t::measured_ms, consensus_handoff_peer_t::measuring, consensus_handoff_message_t::nat_tier, consensus_handoff_peer_t::nat_tier, consensus_handoff_message_t::participant, consensus_handoff_peer_t::pending_capabilities, consensus_handoff_peer_t::pending_nat_tier, consensus_handoff_peer_t::pending_port, consensus_handoff_message_t::port, consensus_handoff_peer_t::port, consensus_handoff_peer_t::probe_started_ms, consensus_handoff_t::ready, consensus_handoff_peer_t::rejected, consensus_handoff_t::round, consensus_handoff_message_t::sequence, consensus_handoff_peer_t::sequence, consensus_handoff_message_t::session, consensus_handoff_t::session, SESSION_ID_SIZE, SET_ERRNO, consensus_handoff_t::successor, consensus_handoff_peer_t::upload_kbps, and consensus_handoff_peer_t::valid.

consensus_handoff_tick()

bool consensus_handoff_tick	(	consensus_handoff_t *	s,
		uint64_t	now,
		consensus_handoff_message_t *	a )

Advance measured successor selection and bounded host-loss recovery. Fresh eligible peers prepare within five seconds; all recovery attempts share one 15-second budget. Only a fresh prepared peer can commit, and failure is terminal.

Parameters

now	Monotonic receiver time in milliseconds.
a	Output action to send when the function returns true.

Returns

True if a PREPARE, COMMIT, or terminal FAILED action was produced.

Definition at line 207 of file handoff.c.

                                                                                                  {
  memset(a, 0, sizeof(*a));
  memcpy(a->session, s->session, SESSION_ID_SIZE);
  a->generation = s->generation;
  if (s->failure_announced)
    return false; // Terminal until the session is recreated.
  if (!s->monitoring) {
    s->monitoring = true;
    s->monitoring_started_ms = now;
  }
  consensus_handoff_peer_t *incumbent = find_peer(s, s->host);
  uint64_t last_host_sample = incumbent && incumbent->valid ? incumbent->measured_ms : s->monitoring_started_ms;
  if (now - last_host_sample > CONSENSUS_HANDOFF_FRESH_MS)
    s->host_lost = true;
  if (s->host_lost && !s->failure_deadline_ms)
    s->failure_deadline_ms = now + CONSENSUS_HANDOFF_RECOVERY_MS;
  // The recovery budget is shared by all candidates, including silent/rejecting
  // candidates that continue sending fresh probes. A late READY cannot revive it.
  if (s->host_lost && now >= s->failure_deadline_ms) {
    s->failure_announced = true;
    s->ready = false;
    memset(s->successor, 0, sizeof(s->successor));
    a->kind = HANDOFF_FAILED;
    a->sequence = s->round;
    handoff_record_action(s, a, now, 0);
    return true;
  }
  if (s->ready && s->host_lost) {
    consensus_handoff_peer_t *p = find_peer(s, s->successor);
    if (p && p->valid && p->capabilities && now - p->measured_ms <= CONSENSUS_HANDOFF_FRESH_MS) {
      a->kind = HANDOFF_COMMIT;
      memcpy(a->participant, s->successor, SESSION_ID_SIZE);
      a->sequence = s->round;
      a->port = p->port;
      a->capabilities = p->capabilities;
      handoff_record_action(s, a, now, 1);
      s->host_sequence = a->sequence;
      memcpy(s->host, s->successor, SESSION_ID_SIZE);
      s->host_lost = false;
      s->monitoring_started_ms = now;
      s->ready = false;
      s->failure_deadline_ms = 0;
      s->failure_announced = false;
      for (size_t i = 0; i < s->count; ++i)
        s->peers[i].rejected = false;
      memset(s->successor, 0, SESSION_ID_SIZE);
      return true;
    }
    s->ready = false;
    memset(s->successor, 0, SESSION_ID_SIZE);
  }
  uint8_t zero[SESSION_ID_SIZE] = {0};
  if (memcmp(s->successor, zero, sizeof(s->successor))) {
    consensus_handoff_peer_t *p = find_peer(s, s->successor);
    if (p && p->valid && p->capabilities && now - p->measured_ms <= CONSENSUS_HANDOFF_FRESH_MS &&
        (s->ready || now < s->prepare_deadline_ms))
      return false;
    if (p && !s->ready)
      p->rejected = true;
    memset(s->successor, 0, SESSION_ID_SIZE);
    s->ready = false;
  }
  participant_metrics_t metrics[MAX_SESSION_PARTICIPANTS];
  size_t count = 0;
  for (size_t i = 0; i < s->count; ++i) {
    consensus_handoff_peer_t *p = &s->peers[i];
    if (!p->valid || p->rejected || !p->capabilities || now - p->measured_ms > CONSENSUS_HANDOFF_FRESH_MS ||
        memcmp(p->id, s->host, SESSION_ID_SIZE) == 0)
      continue;
    participant_metrics_t *m = &metrics[count++];
    memset(m, 0, sizeof(*m));
    memcpy(m->participant_id, p->id, SESSION_ID_SIZE);
    m->nat_tier = p->nat_tier <= 4 ? p->nat_tier : 4;
    m->upload_kbps = p->upload_kbps;
    m->rtt_ns = 500000000; /* Unknown RTT earns no latency bonus. */
  }
  if (!count)
 
    return false;
  int best = -1, backup = -1;
  if (consensus_election_choose_hosts(metrics, (int)count, &best, &backup) != ASCIICHAT_OK)
    return false;
  memcpy(s->successor, metrics[best].participant_id, SESSION_ID_SIZE);
  ++s->round;
  s->prepare_deadline_ms = now + CONSENSUS_HANDOFF_PREPARE_MS;
  a->kind = HANDOFF_PREPARE;
  memcpy(a->participant, s->successor, SESSION_ID_SIZE);
  a->sequence = s->round;
  handoff_record_action(s, a, now, count);
  return true;
}

References ASCIICHAT_OK, consensus_handoff_message_t::capabilities, consensus_handoff_peer_t::capabilities, consensus_election_choose_hosts(), CONSENSUS_HANDOFF_FRESH_MS, CONSENSUS_HANDOFF_PREPARE_MS, CONSENSUS_HANDOFF_RECOVERY_MS, consensus_handoff_t::count, consensus_handoff_t::failure_announced, consensus_handoff_t::failure_deadline_ms, consensus_handoff_message_t::generation, consensus_handoff_t::generation, HANDOFF_COMMIT, HANDOFF_FAILED, HANDOFF_PREPARE, consensus_handoff_t::host, consensus_handoff_t::host_lost, consensus_handoff_t::host_sequence, consensus_handoff_peer_t::id, consensus_handoff_message_t::kind, MAX_SESSION_PARTICIPANTS, consensus_handoff_peer_t::measured_ms, consensus_handoff_t::monitoring, consensus_handoff_t::monitoring_started_ms, consensus_handoff_peer_t::nat_tier, consensus_handoff_message_t::participant, consensus_handoff_t::peers, consensus_handoff_message_t::port, consensus_handoff_peer_t::port, consensus_handoff_t::prepare_deadline_ms, consensus_handoff_t::ready, consensus_handoff_peer_t::rejected, consensus_handoff_t::round, consensus_handoff_message_t::sequence, consensus_handoff_message_t::session, consensus_handoff_t::session, SESSION_ID_SIZE, consensus_handoff_t::successor, consensus_handoff_peer_t::upload_kbps, and consensus_handoff_peer_t::valid.