Home /Modules/advantage/rate_budget.h

rate_budget.h

advantage/trading/rate_budget.h · 85 line(s) · c

/*
 * rate_budget.h - Stay inside a server's published rate limit.
 *
 * Reads the numbers a server tells you (X-RateLimit-Limit, -Remaining, -Reset,
 * and Retry-After) and says how long to wait before the next request, so you
 * take the data you are entitled to at the fastest pace the server allows and
 * no faster. The point is to RESPECT the limit: the budget is spread evenly
 * over the window, a reserve is kept back, and a server's explicit
 * "Retry-After" is always obeyed.
 *
 * Pure: no sockets, no clock, no sleeping. The caller makes the request, feeds
 * the header values in, and does the waiting.
 *
 * Header conventions differ between servers. This module takes the reset as
 * SECONDS FROM NOW. Some APIs send an absolute epoch time instead; convert it
 * first (the C++ layer does, when asked). Retry-After in HTTP-date form is not
 * supported and is reported as a parse error, never guessed.
 *
 * Fail closed: any header value that is present but malformed returns an
 * error and leaves the state unchanged.
 */
#ifndef ADVANTAGE_RATE_BUDGET_H
#define ADVANTAGE_RATE_BUDGET_H

#ifdef __cplusplus
extern "C" {
#endif

#define RB_UNKNOWN (-1.0) /* a value the server has not told us */

typedef enum {
    RB_OK = 0,
    RB_ERR_ARG = -1,   /* NULL pointer or invalid option                  */
    RB_ERR_PARSE = -2, /* a header value is not a plain non-negative number */
    RB_ERR_WAIT = -3   /* required wait exceeds the caller's cap; *out_ms is
                          still set to the wait the server requires        */
} rb_status;

typedef struct {
    double limit;               /* requests allowed per window, or RB_UNKNOWN */
    double remaining;           /* requests left in this window               */
    double reset_seconds;       /* seconds until the window resets            */
    double retry_after_seconds; /* explicit server back-off, or RB_UNKNOWN    */
} rb_state;

void rb_init(rb_state *st);

/*
 * Strict parse of a non-negative decimal number ("120", "0.5"). No sign, no
 * exponent, no hex, no whitespace beyond optional surrounding spaces, and at
 * most 1e12.
 */
rb_status rb_parse_nonneg(const char *text, double *out);

/*
 * Record the header values from one response. A NULL argument means that
 * header was absent: the stored value is kept (except retry_after, which is
 * cleared, because a response without Retry-After lifts the back-off). If any
 * PRESENT value is malformed the call fails and the state is not modified.
 */
rb_status rb_observe(rb_state *st, const char *limit, const char *remaining,
                     const char *reset_seconds, const char *retry_after);

/*
 * Delay before the next request, in milliseconds.
 *   - an explicit Retry-After wins over everything;
 *   - otherwise, if remaining <= reserve, wait out the window (reset);
 *   - otherwise spread the usable budget (remaining - reserve) evenly over the
 *     time left in the window;
 *   - never less than min_interval_ms; unknown headers fall back to it.
 * If the delay exceeds max_wait_ms the call returns RB_ERR_WAIT with *out_ms
 * set to the required wait, so the caller can stop rather than sleep forever.
 */
rb_status rb_next_delay_ms(const rb_state *st, double reserve,
                           double min_interval_ms, double max_wait_ms,
                           double *out_ms);

const char *rb_strerror(rb_status st);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* ADVANTAGE_RATE_BUDGET_H */