metrics.h File Reference

Ring consensus metrics collection and wire protocol. More...

Go to the source code of this file.

Data Structures
struct	__attribute__
	Network quality metrics for a single participant. More...

Typedefs
typedef struct consensus_metrics_collection	consensus_metrics_collection_t
	Opaque metrics collection handle.

Functions
asciichat_error_t	consensus_metrics_measure (const uint8_t my_id[16], participant_metrics_t *out_metrics)
	Measure participant network quality metrics.
asciichat_error_t	consensus_metrics_to_wire (const participant_metrics_t *metrics, participant_metrics_t *out_wire)
	Serialize metrics to wire format with network byte order.
asciichat_error_t	consensus_metrics_from_wire (const participant_metrics_t *wire_metrics, participant_metrics_t *out_metrics)
	Deserialize metrics from wire format.
asciichat_error_t	consensus_metrics_collection_create (consensus_metrics_collection_t **out_collection)
	Create empty metrics collection.
asciichat_error_t	consensus_metrics_collection_add (consensus_metrics_collection_t *collection, const participant_metrics_t *metrics)
	Add metrics to collection.
asciichat_error_t	consensus_metrics_collection_get (const consensus_metrics_collection_t *collection, const participant_metrics_t **out_metrics, int *out_count)
	Get all accumulated metrics.
void	consensus_metrics_collection_destroy (consensus_metrics_collection_t *collection)
	Destroy metrics collection.

Detailed Description

Ring consensus metrics collection and wire protocol.

Handles measurement, serialization, and deserialization of network quality metrics for transmission around the consensus ring. Metrics include:

• NAT tier classification (0=LAN, 1=Public, 2=UPnP, 3=STUN, 4=TURN)
• Upload bandwidth (Kbps)
• Round-trip time (milliseconds)
• STUN probe success rate (0-100%)
• Public address and port information

Wire format uses network byte order (big-endian) for all multi-byte values.

Definition in file metrics.h.

Typedef Documentation

consensus_metrics_collection_t

typedef struct consensus_metrics_collection consensus_metrics_collection_t

Opaque metrics collection handle.

Definition at line 57 of file metrics.h.

Function Documentation

consensus_metrics_collection_add()

asciichat_error_t consensus_metrics_collection_add	(	consensus_metrics_collection_t *	collection,
		const participant_metrics_t *	metrics
	)

Add metrics to collection.

Accumulates metrics from a participant into the collection. Metrics are stored in dynamically-allocated array.

Parameters

collection	Collection to add to
metrics	Metrics to add

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 179 of file metrics.c.

                                                                                         {
  if (!collection || !metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to collection_add");
  }
 
  // Resize if needed
  if (collection->count >= collection->capacity) {
    int new_capacity = collection->capacity * 2;
    participant_metrics_t *new_metrics =
        SAFE_MALLOC(new_capacity * sizeof(participant_metrics_t), participant_metrics_t *);
 
    if (!new_metrics) {
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate metrics array");
    }
 
    // Copy existing metrics
    if (collection->count > 0 && collection->metrics) {
      memcpy(new_metrics, collection->metrics, collection->count * sizeof(participant_metrics_t));
      SAFE_FREE(collection->metrics);
    }
 
    collection->metrics = new_metrics;
    collection->capacity = new_capacity;
  }
 
  // Add new metrics
  if (!collection->metrics) {
    return SET_ERRNO(ERROR_MEMORY, "Collection metrics array is NULL");
  }
 
  memcpy(&collection->metrics[collection->count], metrics, sizeof(*metrics));
  collection->count++;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_metrics_collection::capacity, consensus_metrics_collection::count, ERROR_INVALID_PARAM, ERROR_MEMORY, consensus_metrics_collection::metrics, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

consensus_metrics_collection_create()

asciichat_error_t consensus_metrics_collection_create

(

consensus_metrics_collection_t **

out_collection

)

Create empty metrics collection.

Allocates a collection structure for accumulating metrics from multiple participants during a collection round.

Parameters

out_collection

Output collection handle

Returns

ASCIICHAT_OK on success, error code on failure

Note

Must be freed with consensus_metrics_destroy()

Definition at line 163 of file metrics.c.

                                                                                                       {
  if (!out_collection) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid output parameter");
  }
 
  consensus_metrics_collection_t *collection = SAFE_MALLOC(sizeof(*collection), consensus_metrics_collection_t *);
  memset(collection, 0, sizeof(*collection));
 
  collection->capacity = 10; // Start with capacity for 10 participants
  collection->metrics = SAFE_MALLOC(collection->capacity * sizeof(participant_metrics_t), participant_metrics_t *);
  collection->count = 0;
 
  *out_collection = collection;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_metrics_collection::capacity, consensus_metrics_collection::count, ERROR_INVALID_PARAM, consensus_metrics_collection::metrics, SAFE_MALLOC, and SET_ERRNO.

consensus_metrics_collection_destroy()

void consensus_metrics_collection_destroy

(

consensus_metrics_collection_t *

collection

)

Destroy metrics collection.

Frees all allocated memory in the collection, including the metrics array.

Parameters

collection

Collection to destroy (can be NULL)

Definition at line 228 of file metrics.c.

                                                                                      {
  if (!collection) {
    return;
  }
 
  if (collection->metrics) {
    SAFE_FREE(collection->metrics);
  }
 
  SAFE_FREE(collection);
}

References consensus_metrics_collection::metrics, and SAFE_FREE.

consensus_metrics_collection_get()

asciichat_error_t consensus_metrics_collection_get	(	const consensus_metrics_collection_t *	collection,
		const participant_metrics_t **	out_metrics,
		int *	out_count
	)

Get all accumulated metrics.

Retrieves the accumulated metrics array from collection.

Parameters

collection	Collection to query
out_metrics	Pointer to receive metrics array (not copied, owned by collection)
out_count	Pointer to receive number of metrics

Returns

ASCIICHAT_OK on success, error code on failure

Note

out_metrics points to internal collection storage - do not modify or free

Valid only until collection is destroyed

Definition at line 216 of file metrics.c.

                                                                                                              {
  if (!collection || !out_metrics || !out_count) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to collection_get");
  }
 
  *out_metrics = collection->metrics;
  *out_count = collection->count;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, consensus_metrics_collection::count, ERROR_INVALID_PARAM, consensus_metrics_collection::metrics, and SET_ERRNO.

consensus_metrics_from_wire()

asciichat_error_t consensus_metrics_from_wire	(	const participant_metrics_t *	wire_metrics,
		participant_metrics_t *	out_metrics
	)

Deserialize metrics from wire format.

Converts network byte order values back to host byte order. Inverse operation of consensus_metrics_to_wire().

Parameters

wire_metrics	Input metrics in network byte order
out_metrics	Output metrics in host byte order

Returns

ASCIICHAT_OK on success, error code on failure

Note

out_metrics must point to valid participant_metrics_t allocated by caller

Definition at line 144 of file metrics.c.

                                                                                  {
  if (!wire_metrics || !out_metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to consensus_metrics_from_wire");
  }
 
  // Copy entire structure first
  memcpy(out_metrics, wire_metrics, sizeof(*out_metrics));
 
  // Convert multi-byte fields from network byte order
  out_metrics->upload_kbps = endian_unpack_u32(wire_metrics->upload_kbps);
  out_metrics->rtt_ns = endian_unpack_u32(wire_metrics->rtt_ns);
  out_metrics->public_port = endian_unpack_u16(wire_metrics->public_port);
  out_metrics->measurement_time_ns = endian_unpack_u64(wire_metrics->measurement_time_ns);
  out_metrics->measurement_window_ns = endian_unpack_u64(wire_metrics->measurement_window_ns);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.

consensus_metrics_measure()

asciichat_error_t consensus_metrics_measure	(	const uint8_t	my_id[16],
		participant_metrics_t *	out_metrics
	)

Measure participant network quality metrics.

Collects all metrics needed for host selection:

• NAT tier from detected NAT type (0-4)
• Bandwidth estimate (default 50 Mbps if not available)
• RTT from keepalive pings (default 25ms if not available)
• STUN probe success rate by sending 10 probes

The measurement includes the participant's UUID and timestamps.

Parameters

my_id	Participant UUID (16 bytes)
out_metrics	Output metrics structure (caller-allocated)

Returns

ASCIICHAT_OK on success, error code on failure

Note

out_metrics must point to valid participant_metrics_t allocated by caller

Measurement window and timestamp are set automatically

Definition at line 86 of file metrics.c.

                                                                                                         {
  if (!my_id || !out_metrics) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to consensus_metrics_measure");
  }
 
  // Initialize metrics structure
  memset(out_metrics, 0, sizeof(*out_metrics));
 
  // Copy participant ID
  memcpy(out_metrics->participant_id, my_id, 16);
 
  // NAT tier: Default to 1 (Public IP, no NAT needed)
  // TODO: In production, query NAT detection module
  out_metrics->nat_tier = 1;
 
  // Upload bandwidth: Default 50 Mbps
  out_metrics->upload_kbps = DEFAULT_BANDWIDTH_KBPS;
 
  // RTT: Default 25ms (25,000,000 nanoseconds)
  out_metrics->rtt_ns = DEFAULT_RTT_MS * NS_PER_MS;
 
  // STUN probe success rate: Measure by sending probes
  out_metrics->stun_probe_success_pct = measure_stun_probe_success();
 
  // Public address and port: Placeholder values
  snprintf(out_metrics->public_address, sizeof(out_metrics->public_address), "127.0.0.1");
  out_metrics->public_port = 27224;
 
  // Connection type: Default to direct
  out_metrics->connection_type = 0; // Direct connection
 
  // Measurement time: Current time in nanoseconds
  out_metrics->measurement_time_ns = time_get_realtime_ns();
 
  // Measurement window: 1 second in nanoseconds
  out_metrics->measurement_window_ns = 1 * NS_PER_SEC;
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, DEFAULT_BANDWIDTH_KBPS, DEFAULT_RTT_MS, ERROR_INVALID_PARAM, NS_PER_MS, NS_PER_SEC, SET_ERRNO, and time_get_realtime_ns().

consensus_metrics_to_wire()

asciichat_error_t consensus_metrics_to_wire	(	const participant_metrics_t *	metrics,
		participant_metrics_t *	out_wire
	)

Serialize metrics to wire format with network byte order.

Converts host-order values to network byte order (big-endian) for transmission over the network. Multi-byte fields are converted:

• upload_kbps (uint32_t)
• rtt_ms (uint16_t)
• public_port (uint16_t)
• measurement_time_ms (uint64_t)
• measurement_window_ms (uint32_t)

Parameters

metrics	Input metrics in host byte order
out_wire	Output metrics in network byte order

Returns

ASCIICHAT_OK on success, error code on failure

Note

out_wire must point to valid participant_metrics_t allocated by caller

Definition at line 126 of file metrics.c.

                                                                                                                   {
  if (!metrics || !out_wire) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to consensus_metrics_to_wire");
  }
 
  // Copy entire structure first
  memcpy(out_wire, metrics, sizeof(*out_wire));
 
  // Convert multi-byte fields to network byte order
  out_wire->upload_kbps = endian_pack_u32(metrics->upload_kbps);
  out_wire->rtt_ns = endian_pack_u32(metrics->rtt_ns);
  out_wire->public_port = endian_pack_u16(metrics->public_port);
  out_wire->measurement_time_ns = endian_pack_u64(metrics->measurement_time_ns);
  out_wire->measurement_window_ns = endian_pack_u64(metrics->measurement_window_ns);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, and SET_ERRNO.