mdl_politeness.h

Go to the documentation of this file.

#pragma once
 
#include <stdint.h>
 
#include "ra8_err.h"

typedef void (*mdl_sleep_fn)(void* ctx, uint32_t ms);

typedef struct {
  uint64_t     state;     
  mdl_sleep_fn sleep_fn;  
  void*        sleep_ctx; 
} mdl_politeness_t;

void mdl_politeness_init(mdl_politeness_t* p, uint64_t seed);

void mdl_politeness_init_clock(mdl_politeness_t* p,
                               uint64_t          seed,
                               mdl_sleep_fn      sleep_fn,
                               void*             sleep_ctx);

uint32_t mdl_politeness_wait(mdl_politeness_t* p, uint32_t min_ms, uint32_t max_ms);
 
/* ======================================================================== *
 *  Per-host politeness governor (#301)                                     *
 * ======================================================================== */

typedef int64_t (*mdl_now_fn)(void* ctx);

typedef enum : uint16_t {
  k_mdl_gov_max_hosts  = 16U,    
  k_mdl_gov_host_max   = 128U,   
  k_mdl_gov_level_max  = 16U,    
  k_mdl_gov_ms_per_req = 60000U, 
} mdl_gov_limits_t;

typedef struct {
  uint32_t rate_per_min;    
  uint32_t burst;           
  uint32_t backoff_base_ms; 
  uint32_t backoff_max_ms;  
  uint16_t decay_after;     
  uint16_t max_inflight;    
} mdl_gov_cfg_t;

typedef struct {
  char     host[k_mdl_gov_host_max]; 
  int64_t  credit_ms;                
  int64_t  last_ms;                  
  int64_t  earliest_next_ms;         
  uint16_t backoff_level;            
  uint16_t success_streak;           
  uint16_t inflight;                 
  bool     used;                     
} mdl_host_rec_t;

typedef struct {
  mdl_gov_cfg_t  cfg;                        
  mdl_host_rec_t hosts[k_mdl_gov_max_hosts]; 
  uint64_t       rng;                        
  mdl_now_fn     now_fn;                     
  void*          now_ctx;                    
  mdl_sleep_fn   sleep_fn;                   
  void*          sleep_ctx;                  
} mdl_governor_t;

mdl_gov_cfg_t mdl_gov_cfg_default(void);

void mdl_governor_init(mdl_governor_t* g, const mdl_gov_cfg_t* cfg, uint64_t seed);

void mdl_governor_init_clock(mdl_governor_t*      g,
                             const mdl_gov_cfg_t* cfg,
                             uint64_t             seed,
                             mdl_now_fn           now_fn,
                             void*                now_ctx,
                             mdl_sleep_fn         sleep_fn,
                             void*                sleep_ctx);

ra8_err_t mdl_governor_acquire(mdl_governor_t* g,
                               const char*     host,
                               uint32_t        jitter_min_ms,
                               uint32_t        jitter_max_ms);

void mdl_governor_release(mdl_governor_t* g, const char* host);

void mdl_governor_observe(mdl_governor_t* g,
                          const char*     host,
                          long            status,
                          const char*     retry_after);

void mdl_governor_observe_at_wall(mdl_governor_t* g,
                                  const char*     host,
                                  long            status,
                                  const char*     retry_after,
                                  int64_t         now_wall_s);

bool mdl_governor_peek(const mdl_governor_t* g,
                       const char*           host,
                       uint16_t*             backoff_level,
                       int64_t*              earliest_next_ms);

bool mdl_retry_after_parse(const char* value, int64_t now_wall_s, uint32_t* out_ms);