http3_timing.h
http-3.0/http3_timing.h · 101 line(s) · c
/* ==========================================================================
* http3_timing.h -- SLeeLa HTTP 3.0 connection-level timing: max speed,
* carrier certainty, on-time arrival, and temporal balance.
*
* This layer answers four timing concerns for a stream of packets on one
* connection:
*
* - MAX SPEED : packets must not arrive faster than a configured rate
* (a minimum inter-arrival gap); a burst is flagged.
* - ON TIME : each packet may carry a deadline window; arriving later
* than the allowed lateness is flagged.
* - BALANCED : arrivals should be evenly paced; jitter (deviation of the
* inter-arrival gap from the running mean) beyond a band is
* flagged as unbalanced.
* - CARRIER : a running "carrier certainty" in [0,1] -- the fraction of
* CERTAINTY recent packets that were on time, balanced, and within
* rate -- an estimate of how dependable the path is.
*
* It is ADVISORY and CONNECTION-LEVEL: nothing new travels on the wire, and no
* packet is rejected by timing. The pipeline observes each arrival and records
* flags/counters (see http3_pipeline.h). Timestamps are caller-supplied
* nanoseconds from a monotonic-ish clock; there is no synchronized network
* clock here, so "on time" is measured against the caller's own reference.
*
* Pure data: no I/O, no allocation, no crypto.
* ========================================================================== */
#ifndef HTTP3_TIMING_H
#define HTTP3_TIMING_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* Advisory flags returned by http3_timing_observe (bitwise-OR of concerns). */
typedef enum {
HTTP3_TIMING_OK = 0x00,
HTTP3_TIMING_OVER_RATE = 0x01, /* arrived faster than max speed (burst) */
HTTP3_TIMING_LATE = 0x02, /* arrived after its deadline + tolerance */
HTTP3_TIMING_UNBALANCED= 0x04 /* inter-arrival jitter outside the band */
} http3_timing_flag_t;
/* Default configuration constants (all in nanoseconds unless noted). */
#define HTTP3_TIMING_DEFAULT_MIN_GAP_NS 1000ull /* >= 1us between pkts */
#define HTTP3_TIMING_DEFAULT_LATENESS_NS 50000000ull /* 50ms grace */
#define HTTP3_TIMING_DEFAULT_BALANCE_NS 10000000ull /* +/-10ms jitter band */
#define HTTP3_TIMING_CERTAINTY_WINDOW 64u /* EWMA-ish window */
/*
* Timing state for one connection. Initialize with http3_timing_init, then call
* http3_timing_observe once per received packet with its arrival time (and an
* optional deadline). The struct keeps a running inter-arrival mean and a
* carrier-certainty estimate.
*/
typedef struct {
uint64_t min_gap_ns; /* max speed: minimum allowed inter-arrival gap */
uint64_t lateness_ns; /* on time: allowed lateness past a deadline */
uint64_t balance_ns; /* balanced: allowed jitter around the mean gap */
int have_last; /* 1 once a first packet has been observed */
uint64_t last_arrival_ns; /* arrival time of the previous packet */
double mean_gap_ns; /* running mean inter-arrival gap */
uint64_t observed; /* total packets observed */
double certainty; /* carrier certainty in [0,1] (running estimate) */
} http3_timing_t;
/* Initialize timing with the default bounds (certainty starts at 1.0). */
void http3_timing_init(http3_timing_t *t);
/* Override the bounds (pass 0 for any field to keep its current value). */
void http3_timing_configure(http3_timing_t *t,
uint64_t min_gap_ns,
uint64_t lateness_ns,
uint64_t balance_ns);
/*
* Observe one packet arriving at `arrival_ns`. If `deadline_ns` is non-zero it
* is the time by which the packet should have arrived; arriving later than
* deadline_ns + lateness_ns sets HTTP3_TIMING_LATE. Updates the running mean
* gap and the carrier-certainty estimate. Returns the advisory flags for this
* packet (0 == on time, balanced, within rate).
*/
unsigned http3_timing_observe(http3_timing_t *t,
uint64_t arrival_ns,
uint64_t deadline_ns);
/* Current carrier-certainty estimate in [0,1]. */
double http3_timing_certainty(const http3_timing_t *t);
/* Human-readable name for a single timing flag (for logs/diagnostics). */
const char *http3_timing_flag_name(http3_timing_flag_t flag);
#ifdef __cplusplus
}
#endif
#endif /* HTTP3_TIMING_H */