ascii-chat
Binary v0.16.50-198-g78f51665f
Library lib/v0.3.2-2240-g78f51665f
Video chat in your terminal
Loading...
Searching...
No Matches
consensus.c
Go to the documentation of this file.
1
2/* Storage capacities in elements; text buffers include the terminating NUL. */
3
4#include <recast/defer.h>
8#include <ascii-chat/common.h>
14
15#include "session/consensus.h"
21#include <ascii-chat/common.h>
22#include <ascii-chat/log/log.h>
24#include <string.h>
25
52
59static asciichat_error_t session_consensus_election_bridge(void *context, consensus_state_t *state) {
60 session_consensus_t *consensus = (session_consensus_t *)context;
61 if (!consensus) {
62 return SET_ERRNO(ERROR_INVALID_PARAM, "consensus context is NULL");
63 }
64
65 // Get collected metrics from state
66 int num_metrics = consensus_state_get_metrics_count(state);
67 if (num_metrics < 0) {
68 return SET_ERRNO(ERROR_INVALID_STATE, "No metrics collected");
69 }
70
71 // Allocate array for metrics
72 SAFE_MALLOC_DEFER_FREE(metrics, num_metrics * sizeof(participant_metrics_t), participant_metrics_t *);
73 if (!metrics) {
74 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate metrics array");
75 }
76
77 // Copy metrics from state
78 for (int i = 0; i < num_metrics; i++) {
79 asciichat_error_t err = consensus_state_get_metric_at(state, i, &metrics[i]);
80 if (err != ASCIICHAT_OK) {
81 return err;
82 }
83 }
84
85 // Run election (custom or default)
86 int best_index = -1;
87 int backup_index = -1;
88
89 asciichat_error_t result;
90 if (consensus->election) {
91 // Custom election
92 result = consensus->election(consensus->context, metrics, num_metrics, &best_index, &backup_index);
93 } else {
94 // Default election
95 result = consensus_election_choose_hosts(metrics, num_metrics, &best_index, &backup_index);
96 }
97
98 if (result != ASCIICHAT_OK) {
99 return result;
100 }
101
102 if (best_index < 0 || best_index >= num_metrics) {
103 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid best host index: %d", best_index);
104 }
105
106 if (backup_index < -1 || backup_index >= num_metrics) {
107 return SET_ERRNO(ERROR_INVALID_STATE, "Invalid backup host index: %d", backup_index);
108 }
109
110 result = consensus_state_store_election(state, best_index, backup_index);
111
112 log_info("Session consensus election: best=%d, backup=%d", best_index, backup_index);
113
114 return result;
115}
116
117asciichat_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,
118 const session_consensus_callbacks_t *callbacks, session_consensus_t **out_consensus) {
119 if (!my_id || !callbacks || !out_consensus) {
120 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters: my_id=%p, callbacks=%p, out_consensus=%p", my_id, callbacks, out_consensus);
121 }
122
123 if (!callbacks->send_packet || !callbacks->on_election || !callbacks->get_metrics) {
124 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);
125 }
126
127 if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
128 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
129 }
130
131 // Allocate consensus handle
133 if (!consensus) {
134 return SET_ERRNO(ERROR_MEMORY, "Failed to allocate session consensus");
135 }
136
137 // Copy identity
138 memcpy(consensus->my_id, my_id, SESSION_ID_SIZE);
139 consensus->is_leader = is_leader;
140
141 // Copy callbacks
142 consensus->send_packet = callbacks->send_packet;
143 consensus->on_election = callbacks->on_election;
144 consensus->get_metrics = callbacks->get_metrics;
145 consensus->election = callbacks->election; // May be NULL
146 consensus->context = callbacks->context;
147
148 // Create topology
149 asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, my_id, &consensus->topology);
150 if (err != ASCIICHAT_OK) {
151 SAFE_FREE(consensus);
152 return err;
153 }
154
155 // Create coordinator
156 err = consensus_coordinator_create(my_id, consensus->topology, session_consensus_election_bridge, consensus, &consensus->coordinator);
157 if (err != ASCIICHAT_OK) {
159 SAFE_FREE(consensus);
160 return err;
161 }
162
164
165 log_debug("Session consensus created: my_id=%.*s, is_leader=%d, participants=%d", 16, my_id, is_leader, num_participants);
166
167 *out_consensus = consensus;
168 return ASCIICHAT_OK;
169}
170
172 if (!consensus) {
173 return;
174 }
175
176 if (consensus->coordinator) {
178 }
179
180 if (consensus->topology) {
182 }
183
184 SAFE_FREE(consensus);
185}
186
188 if (!consensus) {
189 return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
190 }
191
192 // Call coordinator process
193 return consensus_coordinator_process(consensus->coordinator, timeout_ms);
194}
195
197 if (!consensus || !participant_ids) {
198 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
199 }
200
201 if (num_participants < 1 || num_participants > MAX_SESSION_PARTICIPANTS) {
202 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count: %d", num_participants);
203 }
204
205 // Validate the candidate before releasing the ring still borrowed by the
206 // coordinator. A rejected membership update must preserve the active round.
207 consensus_topology_t *replacement = NULL;
208 asciichat_error_t err = consensus_topology_create(participant_ids, num_participants, consensus->my_id, &replacement);
209 if (err != ASCIICHAT_OK)
210 return err;
211 err = consensus_coordinator_on_ring_members(consensus->coordinator, replacement);
212 if (err != ASCIICHAT_OK) {
213 consensus_topology_destroy(replacement);
214 return err;
215 }
217 consensus->topology = replacement;
218 return ASCIICHAT_OK;
219}
220
222 if (!consensus) {
223 return SET_ERRNO(ERROR_INVALID_PARAM, "consensus is NULL");
224 }
225
226 return consensus_coordinator_on_collection_start(consensus->coordinator, round_id, deadline_ns);
227}
228
229asciichat_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) {
230 if (!consensus || !sender_id || !metrics) {
231 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
232 }
233
234 return consensus_coordinator_on_stats_update(consensus->coordinator, sender_id, metrics, num_metrics);
235}
236
238 const uint8_t backup_id[SESSION_ID_SIZE], const char backup_address[ACIP_ADDRESS_SIZE], uint16_t backup_port) {
239 if (!consensus || !host_id || !backup_id) {
240 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
241 }
242
243 // First acknowledge the election in coordinator
244 asciichat_error_t err = consensus_coordinator_on_election_result(consensus->coordinator, host_id, backup_id);
245 if (err != ASCIICHAT_OK) {
246 return err;
247 }
248
249 // Then call the mode's election callback
250 if (consensus->on_election) {
251 return consensus->on_election(consensus->context, host_id, host_address, host_port, backup_id, backup_address, backup_port);
252 }
253
254 return ASCIICHAT_OK;
255}
256
258 uint8_t out_backup_id[SESSION_ID_SIZE], char out_backup_address[ACIP_ADDRESS_SIZE], uint16_t *out_backup_port) {
259 if (!consensus || !out_host_id || !out_host_address || !out_host_port || !out_backup_id || !out_backup_address || !out_backup_port) {
260 return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
261 }
262
263 // Get from coordinator
264 asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, out_host_id, out_backup_id);
265 if (err != ASCIICHAT_OK) {
266 return err;
267 }
268
269 // NOTE: The current API doesn't return addresses/ports. This is a limitation
270 // of the coordinator that should be addressed in a future enhancement.
271 // For now, return zeros and indicate this is a placeholder.
272 memset(out_host_address, 0, ACIP_ADDRESS_SIZE);
273 *out_host_port = 0;
274 memset(out_backup_address, 0, ACIP_ADDRESS_SIZE);
275 *out_backup_port = 0;
276
277 return ASCIICHAT_OK;
278}
279
281 if (!consensus) {
282 return false;
283 }
284
285 // Check if we have a valid elected host
286 uint8_t host_id[SESSION_ID_SIZE];
287 uint8_t backup_id[SESSION_ID_SIZE];
288 asciichat_error_t err = consensus_coordinator_get_current_host(consensus->coordinator, host_id, backup_id);
289
290 return err == ASCIICHAT_OK;
291}
292
294 if (!consensus) {
295 return -1;
296 }
297
298 return (int)consensus_coordinator_get_state(consensus->coordinator);
299}
300
302 if (!consensus) {
303 return 0;
304 }
305
307}
308
310 if (!consensus) {
311 return -1;
312 }
313
315}
#define ACIP_ADDRESS_SIZE
Definition acds_sizes.h:11
#define SET_ERRNO(code,...)
Application limits and constraints.
asciichat_error_t session_consensus_process(session_consensus_t *consensus, uint32_t timeout_ms)
Main consensus processing loop - call periodically.
Definition consensus.c:187
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.
Definition consensus.c:196
void session_consensus_destroy(session_consensus_t *consensus)
Destroy consensus instance and free all resources.
Definition consensus.c:171
int session_consensus_get_metrics_count(session_consensus_t *consensus)
Get count of metrics collected in current round.
Definition consensus.c:309
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.
Definition consensus.c:221
bool session_consensus_is_ready(session_consensus_t *consensus)
Check if consensus has completed at least one round.
Definition consensus.c:280
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.
Definition consensus.c:257
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.
Definition consensus.c:117
int session_consensus_get_state(session_consensus_t *consensus)
Get current consensus state.
Definition consensus.c:293
uint64_t session_consensus_time_until_next_round(session_consensus_t *consensus)
Get time until next consensus round in nanoseconds.
Definition consensus.c:301
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).
Definition consensus.c:229
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.
Definition consensus.c:237
struct session_consensus session_consensus_t
When code needs to work with session consensus, it keeps topology, coordinator, send_packet,...
Mode-agnostic ring consensus abstraction for session discovery.
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.
Definition consensus.h:113
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.
Definition consensus.h:98
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.
Definition consensus.h:59
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.
Definition consensus.h:79
void consensus_coordinator_destroy(consensus_coordinator_t *coordinator)
Clean up coordinator resources.
asciichat_error_t consensus_coordinator_get_current_host(const consensus_coordinator_t *coordinator, uint8_t out_host_id[SESSION_ID_SIZE], uint8_t out_backup_id[SESSION_ID_SIZE])
Get currently elected host.
asciichat_error_t consensus_coordinator_create(const uint8_t my_id[SESSION_ID_SIZE], const consensus_topology_t *topology, consensus_election_func_t election_func, void *election_context, consensus_coordinator_t **out_coordinator)
Initialize coordinator with given parameters.
Definition coordinator.c:56
int consensus_coordinator_get_metrics_count(const consensus_coordinator_t *coordinator)
Get count of metrics in current round.
asciichat_error_t consensus_coordinator_on_ring_members(consensus_coordinator_t *coordinator, const consensus_topology_t *new_topology)
Update ring topology when participants change.
struct consensus_coordinator consensus_coordinator_t
Coordinates consensus work for a session: it tracks the participant topology, election state,...
asciichat_error_t consensus_coordinator_process(consensus_coordinator_t *coordinator, uint32_t timeout_ms)
Main orchestration loop.
uint64_t consensus_coordinator_time_until_next_round(const consensus_coordinator_t *coordinator)
Get time until next round.
consensus_state_machine_t consensus_coordinator_get_state(const consensus_coordinator_t *coordinator)
Get current coordinator state.
asciichat_error_t consensus_coordinator_on_election_result(consensus_coordinator_t *coordinator, const uint8_t host_id[SESSION_ID_SIZE], const uint8_t backup_id[SESSION_ID_SIZE])
Handle ELECTION_RESULT packet.
asciichat_error_t consensus_coordinator_on_stats_update(consensus_coordinator_t *coordinator, const uint8_t sender_id[SESSION_ID_SIZE], const participant_metrics_t *metrics, uint8_t num_metrics)
Handle STATS_UPDATE packet.
asciichat_error_t consensus_coordinator_on_collection_start(consensus_coordinator_t *coordinator, uint32_t round_id, uint64_t deadline_ns)
Handle STATS_COLLECTION_START packet.
void consensus_coordinator_set_metrics_provider(consensus_coordinator_t *coordinator, consensus_metrics_provider_fn provider, void *context)
Ring consensus coordinator orchestration.
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
Deterministic host election algorithm.
🔄 Network byte order conversion helpers
unsigned short uint16_t
unsigned int uint32_t
#define SAFE_FREE(ptr)
#define SAFE_MALLOC_DEFER_FREE(name, size, cast)
#define SAFE_CALLOC(count, size, cast)
unsigned long long uint64_t
unsigned char uint8_t
asciichat_error_t
Error and exit codes - unified status values (0-255).
Definition error_codes.h:48
@ ERROR_INVALID_STATE
@ ERROR_MEMORY
Definition error_codes.h:55
@ ASCIICHAT_OK
Definition error_codes.h:50
@ ERROR_INVALID_PARAM
#define MAX_SESSION_PARTICIPANTS
#define SESSION_ID_SIZE
#define log_info(...)
Log an INFO message.
Definition log/log.h:602
#define log_debug(...)
Log a DEBUG message.
Definition log/log.h:589
⚙️ Common definitions, error codes, macros, and types shared throughout the application
📝 Logging API with multiple log levels and terminal output control
Ring consensus metrics collection and wire protocol.
asciichat_error_t consensus_state_get_metric_at(const consensus_state_t *state, int index, participant_metrics_t *out_metrics)
Get collected metrics at index.
Definition state.c:224
asciichat_error_t consensus_state_store_election(consensus_state_t *state, int best_idx, int backup_idx)
Definition state.c:151
struct consensus_state consensus_state_t
State machine instance.
int consensus_state_get_metrics_count(const consensus_state_t *state)
Get count of metrics collected in current round.
Definition state.c:217
Ring consensus state machine.
🔤 String Manipulation and Shell Escaping Utilities
Mode-specific hooks used by the session consensus adapter.
Definition consensus.h:122
void * context
Opaque context passed to all callbacks.
Definition consensus.h:127
session_consensus_election_fn election
Custom election callback (optional, NULL = use default).
Definition consensus.h:126
session_consensus_on_election_fn on_election
Election result callback.
Definition consensus.h:124
session_consensus_get_metrics_fn get_metrics
Measure metrics callback.
Definition consensus.h:125
session_consensus_send_packet_fn send_packet
Send packet callback.
Definition consensus.h:123
When code needs to work with session consensus, it keeps topology, coordinator, send_packet,...
Definition consensus.c:36
consensus_topology_t * topology
Definition consensus.c:38
session_consensus_get_metrics_fn get_metrics
Definition consensus.c:44
session_consensus_on_election_fn on_election
Definition consensus.c:43
consensus_coordinator_t * coordinator
Definition consensus.c:39
session_consensus_send_packet_fn send_packet
Definition consensus.c:42
session_consensus_election_fn election
Definition consensus.c:45
uint8_t my_id[SESSION_ID_SIZE]
Definition consensus.c:49
void consensus_topology_destroy(consensus_topology_t *topology)
Destroy topology.
Definition topology.c:70
asciichat_error_t consensus_topology_create(const uint8_t participant_ids[MAX_SESSION_PARTICIPANTS][SESSION_ID_SIZE], int num_participants, const uint8_t my_id[SESSION_ID_SIZE], consensus_topology_t **out_topology)
Create new ring topology from participant list.
Definition topology.c:43
struct consensus_topology consensus_topology_t
Ring topology for consensus participants.
Ring topology management.