consensus.h File Reference

Mode-agnostic ring consensus abstraction for session discovery. More...

Go to the source code of this file.

Data Structures
struct	session_consensus_callbacks_t
	Mode-specific hooks used by the session consensus adapter. More...

Typedefs
typedef asciichat_error_t(*	session_consensus_send_packet_fn) (void *context, const uint8_t next_participant_id[SESSION_ID_SIZE], const uint8_t *packet, size_t packet_size)
	Callback: Send a consensus packet to the next ring participant.
typedef asciichat_error_t(*	session_consensus_on_election_fn) (void *context, const uint8_t host_id[SESSION_ID_SIZE], const char host_address[ACIP_ADDRESS_SIZE], uint16_t host_port, const uint8_t backup_id[SESSION_ID_SIZE], const char backup_address[ACIP_ADDRESS_SIZE], uint16_t backup_port)
	Callback: Handle elected host result.
typedef asciichat_error_t(*	session_consensus_get_metrics_fn) (void *context, const uint8_t my_id[SESSION_ID_SIZE], participant_metrics_t *out_metrics)
	Callback: Measure current participant's network metrics.
typedef asciichat_error_t(*	session_consensus_election_fn) (void *context, const participant_metrics_t *metrics, int num_metrics, int *out_best_index, int *out_backup_index)
	Callback type for custom election algorithm.

Functions
asciichat_error_t	session_consensus_create (const uint8_t my_id[SESSION_ID_SIZE], bool is_leader, const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants, const session_consensus_callbacks_t *callbacks, session_consensus_t **out_consensus)
	Create a new session consensus instance.
void	session_consensus_destroy (session_consensus_t *consensus)
	Destroy consensus instance and free all resources.
asciichat_error_t	session_consensus_process (session_consensus_t *consensus, uint32_t timeout_ms)
	Main consensus processing loop - call periodically.
asciichat_error_t	session_consensus_set_topology (session_consensus_t *consensus, const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants)
	Update ring topology when participants change.
asciichat_error_t	session_consensus_on_collection_start (session_consensus_t *consensus, uint32_t round_id, uint64_t deadline_ns)
	Handle incoming STATS_COLLECTION_START packet.
asciichat_error_t	session_consensus_on_stats_update (session_consensus_t *consensus, const uint8_t sender_id[SESSION_ID_SIZE], const participant_metrics_t *metrics, uint8_t num_metrics)
	Handle incoming STATS_UPDATE packet (metrics relayed around ring).
asciichat_error_t	session_consensus_on_election_result (session_consensus_t *consensus, const uint8_t host_id[SESSION_ID_SIZE], const char host_address[ACIP_ADDRESS_SIZE], uint16_t host_port, const uint8_t backup_id[SESSION_ID_SIZE], const char backup_address[ACIP_ADDRESS_SIZE], uint16_t backup_port)
	Handle incoming ELECTION_RESULT packet from leader.
asciichat_error_t	session_consensus_get_elected_host (session_consensus_t *consensus, uint8_t out_host_id[SESSION_ID_SIZE], char out_host_address[ACIP_ADDRESS_SIZE], uint16_t *out_host_port, uint8_t out_backup_id[SESSION_ID_SIZE], char out_backup_address[ACIP_ADDRESS_SIZE], uint16_t *out_backup_port)
	Get the currently elected host.
bool	session_consensus_is_ready (session_consensus_t *consensus)
	Check if consensus has completed at least one round.
int	session_consensus_get_state (session_consensus_t *consensus)
	Get current consensus state.
uint64_t	session_consensus_time_until_next_round (session_consensus_t *consensus)
	Get time until next consensus round in nanoseconds.
int	session_consensus_get_metrics_count (session_consensus_t *consensus)
	Get count of metrics collected in current round.

Detailed Description

Mode-agnostic ring consensus abstraction for session discovery.

Provides a clean abstraction over the ring consensus protocol that any mode (server, client, acds, discovery) can use. The abstraction:

• Wraps all consensus modules (state, coordinator, topology, election, metrics)
• Uses callbacks to decouple consensus logic from transport/metrics specifics
• Provides non-blocking periodic processing
• Handles automatic packet generation and state transitions

Design Principles:

1. Consensus algorithm is mode-agnostic - doesn't know about TCP/WebRTC/etc
2. Modes provide callbacks for:
   • Sending packets to next participant
   • Measuring network metrics (NAT quality, bandwidth, etc)
   • Handling elected host results
3. No tight coupling to specific transports or capture mechanisms
4. Each mode can opt-in or opt-out independently

Definition in file consensus.h.

Typedef Documentation

session_consensus_election_fn

typedef asciichat_error_t(* session_consensus_election_fn) (void *context, const participant_metrics_t *metrics, int num_metrics, int *out_best_index, int *out_backup_index)

Callback type for custom election algorithm.

If provided, consensus calls this instead of built-in election. Allows modes to implement custom host selection logic.

Parameters

context	Opaque pointer provided by caller during create
metrics	Array of participant metrics
num_metrics	Count of metrics
out_best_index	Output: Index of best host (not ID)
out_backup_index	Output: Index of backup host

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 120 of file consensus.h.

session_consensus_get_metrics_fn

typedef asciichat_error_t(* session_consensus_get_metrics_fn) (void *context, const uint8_t my_id[SESSION_ID_SIZE], participant_metrics_t *out_metrics)

Callback: Measure current participant's network metrics.

Called by consensus to collect metrics for this participant. Should measure:

• NAT tier (0=LAN, 1=Public, 2=UPnP, 3=STUN, 4=TURN)
• Upload bandwidth (Kbps)
• RTT to current host (nanoseconds)
• STUN probe success rate (0-100%)
• Public address and port
• Connection type (Direct, UPnP, STUN, TURN)

Parameters

context	Opaque pointer provided by caller during create
my_id	16-byte UUID of this participant
out_metrics	Output metrics structure (caller-allocated)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 104 of file consensus.h.

session_consensus_on_election_fn

typedef asciichat_error_t(* session_consensus_on_election_fn) (void *context, const uint8_t host_id[SESSION_ID_SIZE], const char host_address[ACIP_ADDRESS_SIZE], uint16_t host_port, const uint8_t backup_id[SESSION_ID_SIZE], const char backup_address[ACIP_ADDRESS_SIZE], uint16_t backup_port)

Callback: Handle elected host result.

Called by consensus when a new host election is complete and announced. The mode should:

• Store the elected host and backup host info
• Update connection targets if participant
• Initiate host role if elected as new host

Parameters

context	Opaque pointer provided by caller during create
host_id	16-byte UUID of elected host
host_address	Address to connect to (hostname or IP)
host_port	Port to connect to
backup_id	16-byte UUID of backup host
backup_address	Backup address
backup_port	Backup port

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 81 of file consensus.h.

session_consensus_send_packet_fn

typedef asciichat_error_t(* session_consensus_send_packet_fn) (void *context, const uint8_t next_participant_id[SESSION_ID_SIZE], const uint8_t *packet, size_t packet_size)

Callback: Send a consensus packet to the next ring participant.

Called by consensus to send packets around the ring. The mode is responsible for serializing and transmitting to the appropriate transport.

Parameters

context	Opaque pointer provided by caller during create
next_participant_id	16-byte UUID of next participant in ring
packet	Packet data to send (including header)
packet_size	Size of packet in bytes

Returns

ASCIICHAT_OK on success, error code if sending failed

Definition at line 59 of file consensus.h.

Function Documentation

session_consensus_create()

asciichat_error_t session_consensus_create	(	const uint8_t	my_id[SESSION_ID_SIZE],
		bool	is_leader,
		const uint8_t	participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE],
		int	num_participants,
		const session_consensus_callbacks_t *	callbacks,
		session_consensus_t **	out_consensus )

Create a new session consensus instance.

Initializes consensus for a participant in a session. The consensus will manage ring topology, metrics collection, and host election according to the configured ring parameters.

Parameters

my_id	16-byte UUID of this participant
is_leader	Whether this participant should run elections (typically last in ring)
participant_ids	Array of participant UUIDs (up to 128)
num_participants	Count of participants
callbacks	Callback functions for mode integration
out_consensus	Output consensus handle (caller must destroy)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 117 of file consensus.c.

                                                                                {
  if (!my_id || !callbacks || !out_consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: my_id=%p, callbacks=%p, out_consensus=%p", my_id,
                     callbacks, out_consensus);
  }
 
  if (!callbacks->send_packet || !callbacks->on_election || !callbacks->get_metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Required callbacks missing: send_packet=%p, on_election=%p, get_metrics=%p",
                     callbacks->send_packet, callbacks->on_election, callbacks->get_metrics);
  }
 
  if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
  }
 
  // Allocate consensus handle
  session_consensus_t *consensus = SAFE_CALLOC(1, sizeof(session_consensus_t), session_consensus_t *);
  if (!consensus) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate session consensus");
  }
 
  // Copy identity
  memcpy(consensus->my_id, my_id, SESSION_ID_SIZE);
  consensus->is_leader = is_leader;
 
  // Copy callbacks
  consensus->send_packet = callbacks->send_packet;
  consensus->on_election = callbacks->on_election;
  consensus->get_metrics = callbacks->get_metrics;
  consensus->election = callbacks->election; // May be NULL
  consensus->context = callbacks->context;
 
  // Create topology
  asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, my_id, &consensus->topology);
  if (err != ASCIICHAT_OK) {
    SAFE_FREE(consensus);
    return err;
  }
 
  // Create coordinator
  err = consensus_coordinator_create(my_id, consensus->topology, session_consensus_election_bridge, consensus,
                                     &consensus->coordinator);
  if (err != ASCIICHAT_OK) {
    consensus_topology_destroy(consensus->topology);
    SAFE_FREE(consensus);
    return err;
  }
 
  consensus_coordinator_set_metrics_provider(consensus->coordinator, callbacks->get_metrics, callbacks->context);
 
  log_debug("Session consensus created: my_id=%.*s, is_leader=%d, participants=%d", 16, my_id, is_leader,
            num_participants);
 
  *out_consensus = consensus;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_coordinator_create(), consensus_coordinator_set_metrics_provider(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::context, session_consensus_callbacks_t::context, session_consensus::coordinator, session_consensus::election, session_consensus_callbacks_t::election, ERROR_INVALID_PARAM, ERROR_MEMORY, session_consensus::get_metrics, session_consensus_callbacks_t::get_metrics, session_consensus::is_leader, log_debug, MAX_SESSION_PARTICIPANTS, session_consensus::my_id, session_consensus::on_election, session_consensus_callbacks_t::on_election, SAFE_CALLOC, SAFE_FREE, session_consensus::send_packet, session_consensus_callbacks_t::send_packet, SESSION_ID_SIZE, SET_ERRNO, and session_consensus::topology.

Referenced by consensus_create_for_discovery().

session_consensus_destroy()

void session_consensus_destroy

(

session_consensus_t *

consensus

)

Destroy consensus instance and free all resources.

Parameters

consensus

Consensus handle (safe to pass NULL)

Definition at line 177 of file consensus.c.

                                                               {
  if (!consensus) {
    return;
  }
 
  if (consensus->coordinator) {
    consensus_coordinator_destroy(consensus->coordinator);
  }
 
  if (consensus->topology) {
    consensus_topology_destroy(consensus->topology);
  }
 
  SAFE_FREE(consensus);
}

References consensus_coordinator_destroy(), consensus_topology_destroy(), session_consensus::coordinator, SAFE_FREE, and session_consensus::topology.

session_consensus_get_elected_host()

asciichat_error_t session_consensus_get_elected_host	(	session_consensus_t *	consensus,
		uint8_t	out_host_id[SESSION_ID_SIZE],
		char	out_host_address[ACIP_ADDRESS_SIZE],
		uint16_t *	out_host_port,
		uint8_t	out_backup_id[SESSION_ID_SIZE],
		char	out_backup_address[ACIP_ADDRESS_SIZE],
		uint16_t *	out_backup_port )

Get the currently elected host.

Returns the most recently elected host and backup. If no election has completed yet, returns the previous stored result if available, or error.

Parameters

consensus	Consensus handle
out_host_id	Output: 16-byte UUID of host (caller provides buffer)
out_host_address	Output: Host address (caller provides buffer, 64 bytes)
out_host_port	Output: Host port
out_backup_id	Output: 16-byte UUID of backup (caller provides buffer)
out_backup_address	Output: Backup address (caller provides buffer, 64 bytes)
out_backup_port	Output: Backup port

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 274 of file consensus.c.

                                                                                {
  if (!consensus || !out_host_id || !out_host_address || !out_host_port || !out_backup_id || !out_backup_address ||
      !out_backup_port) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // Get from coordinator
  asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, out_host_id, out_backup_id);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // NOTE: The current API doesn't return addresses/ports. This is a limitation
  // of the coordinator that should be addressed in a future enhancement.
  // For now, return zeros and indicate this is a placeholder.
  memset(out_host_address, 0, ACIP_ADDRESS_SIZE);
  *out_host_port = 0;
  memset(out_backup_address, 0, ACIP_ADDRESS_SIZE);
  *out_backup_port = 0;
 
  return ASCIICHAT_OK;
}

References ACIP_ADDRESS_SIZE, ASCIICHAT_OK, consensus_coordinator_get_current_host(), session_consensus::coordinator, ERROR_INVALID_PARAM, SESSION_ID_SIZE, and SET_ERRNO.

session_consensus_get_metrics_count()

int session_consensus_get_metrics_count

(

session_consensus_t *

consensus

)

Get count of metrics collected in current round.

Useful for monitoring collection progress.

Parameters

consensus

Consensus handle

Returns

Number of metrics collected, or -1 if invalid

Definition at line 331 of file consensus.c.

                                                                        {
  if (!consensus) {
    return -1;
  }
 
  return consensus_coordinator_get_metrics_count(consensus->coordinator);
}

References consensus_coordinator_get_metrics_count(), and session_consensus::coordinator.

session_consensus_get_state()

int session_consensus_get_state

(

session_consensus_t *

consensus

)

Get current consensus state.

Parameters

consensus

Consensus handle

Returns

Current state from internal state machine

Definition at line 315 of file consensus.c.

                                                                {
  if (!consensus) {
    return -1;
  }
 
  return (int)consensus_coordinator_get_state(consensus->coordinator);
}

References consensus_coordinator_get_state(), and session_consensus::coordinator.

session_consensus_is_ready()

bool session_consensus_is_ready

(

session_consensus_t *

consensus

)

Check if consensus has completed at least one round.

Returns true if at least one complete consensus round has finished with a valid elected host and backup.

Parameters

consensus

Consensus handle

Returns

true if consensus reached, false otherwise

Definition at line 302 of file consensus.c.

                                                                {
  if (!consensus) {
    return false;
  }
 
  // Check if we have a valid elected host
  uint8_t host_id[SESSION_ID_SIZE];
  uint8_t backup_id[SESSION_ID_SIZE];
  asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, host_id, backup_id);
 
  return err == ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_coordinator_get_current_host(), session_consensus::coordinator, and SESSION_ID_SIZE.

session_consensus_on_collection_start()

asciichat_error_t session_consensus_on_collection_start	(	session_consensus_t *	consensus,
		uint32_t	round_id,
		uint64_t	deadline_ns )

Handle incoming STATS_COLLECTION_START packet.

Consensus calls this when it receives a collection start from the previous ring participant. Should be called from packet handler in mode.

Parameters

consensus	Consensus handle
round_id	Collection round ID
deadline_ns	Unix nanosecond deadline for collection

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 230 of file consensus.c.

                                                                              {
  if (!consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
  }
 
  return consensus_coordinator_on_collection_start(consensus->coordinator, round_id, deadline_ns);
}

References consensus_coordinator_on_collection_start(), session_consensus::coordinator, ERROR_INVALID_PARAM, and SET_ERRNO.

session_consensus_on_election_result()

asciichat_error_t session_consensus_on_election_result	(	session_consensus_t *	consensus,
		const uint8_t	host_id[SESSION_ID_SIZE],
		const char	host_address[ACIP_ADDRESS_SIZE],
		uint16_t	host_port,
		const uint8_t	backup_id[SESSION_ID_SIZE],
		const char	backup_address[ACIP_ADDRESS_SIZE],
		uint16_t	backup_port )

Handle incoming ELECTION_RESULT packet from leader.

Consensus calls this when leader announces the elected host. Should be called from packet handler in mode.

Parameters

consensus	Consensus handle
host_id	16-byte UUID of elected host
host_address	Address of elected host
host_port	Port of elected host
backup_id	16-byte UUID of backup host
backup_address	Address of backup host
backup_port	Port of backup host

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 249 of file consensus.c.

                                                                             {
  if (!consensus || !host_id || !backup_id) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // First acknowledge the election in coordinator
  asciichat_error_t err = consensus_coordinator_on_election_result(consensus->coordinator, host_id, backup_id);
  if (err != ASCIICHAT_OK) {
    return err;
  }
 
  // Then call the mode's election callback
  if (consensus->on_election) {
    return consensus->on_election(consensus->context, host_id, host_address, host_port, backup_id, backup_address,
                                  backup_port);
  }
 
  return ASCIICHAT_OK;
}

References ACIP_ADDRESS_SIZE, ASCIICHAT_OK, consensus_coordinator_on_election_result(), session_consensus::context, session_consensus::coordinator, ERROR_INVALID_PARAM, session_consensus::on_election, SESSION_ID_SIZE, and SET_ERRNO.

session_consensus_on_stats_update()

asciichat_error_t session_consensus_on_stats_update	(	session_consensus_t *	consensus,
		const uint8_t	sender_id[SESSION_ID_SIZE],
		const participant_metrics_t *	metrics,
		uint8_t	num_metrics )

Handle incoming STATS_UPDATE packet (metrics relayed around ring).

Consensus calls this when it receives metrics from the previous participant. Should be called from packet handler in mode.

Parameters

consensus	Consensus handle
sender_id	16-byte UUID of who sent this update
metrics	Array of metrics in this packet
num_metrics	Count of metrics

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 239 of file consensus.c.

                                                                                                               {
  if (!consensus || !sender_id || !metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  return consensus_coordinator_on_stats_update(consensus->coordinator, sender_id, metrics, num_metrics);
}

References consensus_coordinator_on_stats_update(), session_consensus::coordinator, ERROR_INVALID_PARAM, SESSION_ID_SIZE, and SET_ERRNO.

session_consensus_process()

asciichat_error_t session_consensus_process	(	session_consensus_t *	consensus,
		uint32_t	timeout_ms )

Main consensus processing loop - call periodically.

Handles:

• Round scheduling (every 5 minutes)
• Collection deadline enforcement (30 seconds)
• Metrics measurement and relay around ring
• Election computation (leader only)
• Result broadcasting

Non-blocking: returns immediately if no action needed. Modes should call this regularly (at least once per second) to ensure timely round scheduling and deadline enforcement.

Parameters

consensus	Consensus handle
timeout_ms	Timeout for this call in milliseconds (0 = non-blocking)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 193 of file consensus.c.

                                                                                                 {
  if (!consensus) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
  }
 
  // Call coordinator process
  return consensus_coordinator_process(consensus->coordinator, timeout_ms);
}

References consensus_coordinator_process(), session_consensus::coordinator, ERROR_INVALID_PARAM, and SET_ERRNO.

session_consensus_set_topology()

asciichat_error_t session_consensus_set_topology	(	session_consensus_t *	consensus,
		const uint8_t	participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE],
		int	num_participants )

Update ring topology when participants change.

Called when the ring topology changes (participants join/leave). Updates the consensus topology and resets any in-progress round.

Parameters

consensus	Consensus handle
participant_ids	Updated array of participant UUIDs
num_participants	New count of participants

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 203 of file consensus.c.

                                                     {
  if (!consensus || !participant_ids) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
  }
 
  // Validate the candidate before releasing the ring still borrowed by the
  // coordinator. A rejected membership update must preserve the active round.
  consensus_topology_t *replacement = NULL;
  asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, consensus->my_id, &replacement);
  if (err != ASCIICHAT_OK)
    return err;
  err = consensus_coordinator_on_ring_members(consensus->coordinator, replacement);
  if (err != ASCIICHAT_OK) {
    consensus_topology_destroy(replacement);
    return err;
  }
  consensus_topology_destroy(consensus->topology);
  consensus->topology = replacement;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_coordinator_on_ring_members(), consensus_topology_create(), consensus_topology_destroy(), session_consensus::coordinator, ERROR_INVALID_PARAM, MAX_SESSION_PARTICIPANTS, session_consensus::my_id, SESSION_ID_SIZE, SET_ERRNO, and session_consensus::topology.

session_consensus_time_until_next_round()

uint64_t session_consensus_time_until_next_round

(

session_consensus_t *

consensus

)

Get time until next consensus round in nanoseconds.

Useful for scheduling when to call process() next.

Parameters

consensus

Consensus handle

Returns

Nanoseconds until next round, or 0 if round is due now

Definition at line 323 of file consensus.c.

                                                                                 {
  if (!consensus) {
    return 0;
  }
 
  return consensus_coordinator_time_until_next_round(consensus->coordinator);
}

References consensus_coordinator_time_until_next_round(), and session_consensus::coordinator.

Referenced by consensus_suggest_timeout_ms().