ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
election.c File Reference

Deterministic election algorithm. More...

Go to the source code of this file.

Functions

uint32_t consensus_election_compute_score (const participant_metrics_t *metrics)
 Compute deterministic score for a participant.
asciichat_error_t consensus_election_choose_hosts (const participant_metrics_t *metrics, int num_metrics, int *out_best_index, int *out_backup_index)
 Elect best and backup host from metrics.
asciichat_error_t consensus_election_verify (const participant_metrics_t *metrics, int num_metrics, const uint8_t announced_host_id[SESSION_ID_SIZE], const uint8_t announced_backup_id[SESSION_ID_SIZE], bool *out_valid)
 Verify election result matches expected scores.

Detailed Description

Deterministic election algorithm.

Definition in file election.c.

Function Documentation

◆ consensus_election_choose_hosts()

asciichat_error_t consensus_election_choose_hosts ( const participant_metrics_t * metrics,
int num_metrics,
int * out_best_index,
int * out_backup_index )

Elect best and backup host from metrics.

Returns indices of best and second-best participants. Deterministic tie-breaking ensures identical result on all clients.

Definition at line 78 of file election.c.

78 {
79 if (!metrics || !out_best_index || !out_backup_index || num_metrics < 1) {
80 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid election parameters");
81 }
82
83 for (int i = 0; i < num_metrics; ++i) {
84 if (metrics[i].nat_tier > 4 || metrics[i].stun_probe_success_pct > 100)
85 return SET_ERRNO(ERROR_INVALID_PARAM, "Malformed participant metrics");
86 for (int j = 0; j < i; ++j)
87 if (!memcmp(metrics[i].participant_id, metrics[j].participant_id, SESSION_ID_SIZE))
88 return SET_ERRNO(ERROR_INVALID_PARAM, "Duplicate election participant");
89 }
90
91 // Compute scores for all participants
92 uint32_t *scores = SAFE_MALLOC(sizeof(uint32_t) * num_metrics, uint32_t *);
93
94 for (int i = 0; i < num_metrics; i++) {
95 scores[i] = consensus_election_compute_score(&metrics[i]);
96 }
97
98 // Find best and second-best
99 find_best_two(metrics, scores, num_metrics, out_best_index, out_backup_index);
100
101 SAFE_FREE(scores);
102 return ASCIICHAT_OK;
103}
#define SET_ERRNO(code,...)
uint32_t consensus_election_compute_score(const participant_metrics_t *metrics)
Compute deterministic score for a participant.
Definition election.c:14
unsigned int uint32_t
#define SAFE_FREE(ptr)
#define SAFE_MALLOC(size, cast)
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM
#define SESSION_ID_SIZE
uint8_t participant_id[SESSION_ID_SIZE]

References ASCIICHAT_OK, consensus_election_compute_score(), ERROR_INVALID_PARAM, participant_id, SAFE_FREE, SAFE_MALLOC, SESSION_ID_SIZE, and SET_ERRNO.

Referenced by consensus_election_verify(), consensus_handoff_tick(), and consensus_state_compute_election().

◆ consensus_election_compute_score()

uint32_t consensus_election_compute_score ( const participant_metrics_t * metrics)

Compute deterministic score for a participant.

Higher score = better host candidate

score = (4 - nat_tier) * 1000 // NAT tier: 0=best, 4=worst

  • (upload_kbps / 10) // Bandwidth bonus
  • (500 - rtt_ms) // Latency bonus
  • stun_probe_success_pct // Network stability

Definition at line 14 of file election.c.

14 {
15 if (!metrics || metrics->nat_tier > 4 || metrics->stun_probe_success_pct > 100)
16 return 0;
17
18 // NAT tier: 0=LAN (best), 4=TURN (worst)
19 // (4 - tier) * 1000 makes LAN score 4000, TURN score 0
20 uint32_t nat_score = (4 - metrics->nat_tier) * 1000;
21
22 // Bandwidth: higher is better
23 // Divide by 10 to keep in reasonable scale (10Mbps = +1000)
24 uint32_t bw_score = metrics->upload_kbps / 10;
25
26 // Latency: lower is better
27 // (500ms - rtt_ns) means 0ns RTT = +500, 500ms = 0, high latency = negative (but capped at 0)
28 // 500ms = 500,000,000ns
29 uint32_t rtt_score = (metrics->rtt_ns < 500 * NS_PER_MS) ? (500 - (metrics->rtt_ns / NS_PER_MS)) : 0;
30
31 // STUN probe success: 0-100%
32 uint32_t probe_score = metrics->stun_probe_success_pct;
33
34 // Total score
35 uint32_t total = nat_score + bw_score + rtt_score + probe_score;
36 return total;
37}
#define NS_PER_MS
Definition time.h:163

References NS_PER_MS.

Referenced by consensus_election_choose_hosts().

◆ consensus_election_verify()

asciichat_error_t consensus_election_verify ( const participant_metrics_t * metrics,
int num_metrics,
const uint8_t announced_host_id[SESSION_ID_SIZE],
const uint8_t announced_backup_id[SESSION_ID_SIZE],
bool * out_valid )

Verify election result matches expected scores.

Independent verification that leader's decision is correct. Used by all clients to validate election before accepting.

Definition at line 105 of file election.c.

106 {
107 if (!metrics || !announced_host_id || !announced_backup_id || !out_valid) {
108 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid verification parameters");
109 }
110
111 // Find which indices the announced IDs correspond to
112 int host_idx = -1, backup_idx = -1;
113
114 for (int i = 0; i < num_metrics; i++) {
115 if (memcmp(metrics[i].participant_id, announced_host_id, SESSION_ID_SIZE) == 0) {
116 host_idx = i;
117 }
118 if (memcmp(metrics[i].participant_id, announced_backup_id, SESSION_ID_SIZE) == 0) {
119 backup_idx = i;
120 }
121 }
122
123 // If we can't find announced IDs, result is invalid
124 if (host_idx < 0) {
125 *out_valid = false;
126 return ASCIICHAT_OK;
127 }
128
129 // Run our own election
130 int computed_host, computed_backup;
131 asciichat_error_t err = consensus_election_choose_hosts(metrics, num_metrics, &computed_host, &computed_backup);
132
133 if (err != ASCIICHAT_OK) {
134 return err;
135 }
136
137 // Check if computed result matches announced
138 uint8_t no_backup[SESSION_ID_SIZE] = {0};
139 *out_valid = host_idx == computed_host && (computed_backup < 0 ? memcmp(announced_backup_id, no_backup, sizeof(no_backup)) == 0 : backup_idx == computed_backup);
140 return ASCIICHAT_OK;
141}
asciichat_error_t consensus_election_choose_hosts(const participant_metrics_t *metrics, int num_metrics, int *out_best_index, int *out_backup_index)
Elect best and backup host from metrics.
Definition election.c:78
unsigned char uint8_t
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48

References ASCIICHAT_OK, consensus_election_choose_hosts(), ERROR_INVALID_PARAM, participant_id, SESSION_ID_SIZE, and SET_ERRNO.