rate_limit.h File Reference

🚦 Rate limiting API with pluggable backends More...

Go to the source code of this file.

Data Structures
struct	rate_limit_config_t
	One sliding-window rate-limit policy. More...
struct	rate_limiter_backend_ops_t
	Backend callbacks implementing rate-limit checks, recording, cleanup, and destruction. More...

Typedefs
typedef struct rate_limiter_s	rate_limiter_t
	Opaque rate limiter handle.

Enumerations
enum	rate_event_type_t {   RATE_EVENT_SESSION_CREATE = 0 , RATE_EVENT_SESSION_LOOKUP = 1 , RATE_EVENT_SESSION_JOIN = 2 , RATE_EVENT_CONNECTION = 3 ,   RATE_EVENT_IMAGE_FRAME = 4 , RATE_EVENT_AUDIO = 5 , RATE_EVENT_PING = 6 , RATE_EVENT_CLIENT_JOIN = 7 ,   RATE_EVENT_CONTROL = 8 , RATE_EVENT_HTTP_REQUEST = 9 , RATE_EVENT_MAX }
	One sliding-window rate-limit policy. More...

Functions
rate_limiter_t *	rate_limiter_create_memory (void)
	Create in-memory rate limiter.
rate_limiter_t *	rate_limiter_create_sqlite (const char *db_path)
	Create SQLite-backed rate limiter.
void	rate_limiter_set_sqlite_db (rate_limiter_t *limiter, void *db)
	Set SQLite database handle for rate limiter.
void	rate_limiter_destroy (rate_limiter_t *limiter)
	Destroy rate limiter and free resources.
asciichat_error_t	rate_limiter_check (rate_limiter_t *limiter, const char *ip_address, rate_event_type_t event_type, const rate_limit_config_t *config, bool *allowed)
	Check if an event from an IP address should be rate limited.
asciichat_error_t	rate_limiter_record (rate_limiter_t *limiter, const char *ip_address, rate_event_type_t event_type)
	Record a rate limit event.
asciichat_error_t	rate_limiter_prune (rate_limiter_t *limiter, uint32_t max_age_secs)
	Clean up old rate limit events.
const char *	rate_limiter_event_type_string (rate_event_type_t event_type)
	Get event type string for logging/database storage.

Variables
const rate_limit_config_t	DEFAULT_RATE_LIMITS [RATE_EVENT_MAX]
	Default rate limits for each event type.

Detailed Description

🚦 Rate limiting API with pluggable backends

Supports two backends:

• Memory: Thread-safe in-memory tracking with uthash (for ascii-chat server)
• SQLite: Persistent database tracking (for acds discovery server)

Example usage:

// Create in-memory rate limiter
rate_limiter_t *limiter = rate_limiter_create_memory();
 
// Or SQLite-backed limiter
rate_limiter_t *limiter = rate_limiter_create_sqlite("acds.db");
 
// Check rate limit
bool allowed = false;
rate_limiter_check(limiter, "192.168.1.100", RATE_EVENT_SESSION_CREATE, NULL, &allowed);
 
if (allowed) {
    rate_limiter_record(limiter, "192.168.1.100", RATE_EVENT_SESSION_CREATE);
    // Process request
} else {
    // Reject request
}
 
// Cleanup (call periodically)
rate_limiter_prune(limiter, 3600);
 
// Destroy
rate_limiter_destroy(limiter);

Definition in file rate_limit.h.

Typedef Documentation

rate_limiter_t

typedef struct rate_limiter_s rate_limiter_t

Opaque rate limiter handle.

Backend implementation is hidden from users.

Definition at line 83 of file rate_limit.h.

Enumeration Type Documentation

rate_event_type_t

enum rate_event_type_t

One sliding-window rate-limit policy.

Backend callbacks implementing rate-limit checks, recording, cleanup, and destruction

Rate limit event types

Enumerator
RATE_EVENT_SESSION_CREATE	Session creation.
RATE_EVENT_SESSION_LOOKUP	Session lookup.
RATE_EVENT_SESSION_JOIN	Session join.
RATE_EVENT_CONNECTION	New connection.
RATE_EVENT_IMAGE_FRAME	Image frame from client (PACKET_TYPE_IMAGE_FRAME).
RATE_EVENT_AUDIO	Audio packet (PACKET_TYPE_AUDIO, PACKET_TYPE_AUDIO_BATCH).
RATE_EVENT_PING	Ping/pong keepalive (PACKET_TYPE_PING, PACKET_TYPE_PONG).
RATE_EVENT_CLIENT_JOIN	Client join request (PACKET_TYPE_CLIENT_JOIN).
RATE_EVENT_CONTROL	Control packets (CAPABILITIES, STREAM_START/STOP, LEAVE).
RATE_EVENT_HTTP_REQUEST	HTTP requests from a client identity.
RATE_EVENT_MAX	Sentinel value.

Definition at line 48 of file rate_limit.h.

             {
  // ACDS discovery server events
  RATE_EVENT_SESSION_CREATE = 0, 
  RATE_EVENT_SESSION_LOOKUP = 1, 
  RATE_EVENT_SESSION_JOIN = 2,   
 
  // ascii-chat server events
  RATE_EVENT_CONNECTION = 3,   
  RATE_EVENT_IMAGE_FRAME = 4,  
  RATE_EVENT_AUDIO = 5,        
  RATE_EVENT_PING = 6,         
  RATE_EVENT_CLIENT_JOIN = 7,  
  RATE_EVENT_CONTROL = 8,      
  RATE_EVENT_HTTP_REQUEST = 9, 
 
  RATE_EVENT_MAX 
} rate_event_type_t;

Function Documentation

rate_limiter_check()

asciichat_error_t rate_limiter_check	(	rate_limiter_t *	limiter,
		const char *	ip_address,
		rate_event_type_t	event_type,
		const rate_limit_config_t *	config,
		bool *	allowed )

Check if an event from an IP address should be rate limited.

Uses sliding window: counts events in the last window_secs seconds.

Parameters

	limiter	Rate limiter instance
	ip_address	IP address string (IPv4 or IPv6)
	event_type	Type of event
	config	Rate limit configuration (NULL = use defaults)
[out]	allowed	True if event is allowed, false if rate limited

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 138 of file rate_limit.c.

                                                                                       {
  ASCII_OTEL_SCOPE(RATE_LIMITER_CHECK);
  if (!limiter || !limiter->ops || !limiter->ops->check) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid rate limiter");
  }
 
  if (!ip_address || !allowed) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ip_address or allowed is NULL");
  }
 
  if (event_type >= RATE_EVENT_MAX) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid event_type: %d", event_type);
  }
 
  ASCII_OTEL_ATTR_STRING("rate_limit.event", rate_limiter_event_type_string(event_type));
  asciichat_error_t result = limiter->ops->check(limiter->backend_data, ip_address, event_type, config, allowed);
  if (result == ASCIICHAT_OK)
    ASCII_OTEL_ATTR_INT("rate_limit.allowed", *allowed);
  if (result == ASCIICHAT_OK && !*allowed)
    stats_counter_add(stats_runtime_scope(), STATS_COUNTER_RATE_LIMIT_REJECTIONS, 1);
  return result;
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ASCII_OTEL_SCOPE, ASCIICHAT_OK, rate_limiter_s::backend_data, rate_limiter_backend_ops_t::check, ERROR_INVALID_PARAM, rate_limiter_s::ops, RATE_EVENT_MAX, rate_limiter_event_type_string(), SET_ERRNO, stats_counter_add(), STATS_COUNTER_RATE_LIMIT_REJECTIONS, and stats_runtime_scope().

Referenced by check_and_record_rate_limit(), and http_server_dispatch_http3().

rate_limiter_create_memory()

rate_limiter_t * rate_limiter_create_memory

(

void

)

Create in-memory rate limiter.

Thread-safe implementation using uthash and mutexes. Suitable for ascii-chat server where persistence is not needed.

Returns

Rate limiter instance or NULL on failure

Definition at line 83 of file rate_limit.c.

                                                 {
  rate_limiter_t *limiter = malloc(sizeof(rate_limiter_t));
  if (!limiter) {
    log_error("Failed to allocate rate limiter");
    return NULL;
  }
 
  limiter->backend_data = memory_backend_create();
  if (!limiter->backend_data) {
    free(limiter);
    return NULL;
  }
 
  limiter->ops = &memory_backend_ops;
  return limiter;
}

References rate_limiter_s::backend_data, log_error, memory_backend_create(), memory_backend_ops, and rate_limiter_s::ops.

Referenced by http_server_init().

rate_limiter_create_sqlite()

rate_limiter_t * rate_limiter_create_sqlite

(

const char *

db_path

)

Create SQLite-backed rate limiter.

Persistent implementation using SQLite database. Suitable for acds discovery server where persistence is needed.

Parameters

db_path

Path to SQLite database (NULL = externally managed database)

Returns

Rate limiter instance or NULL on failure

Definition at line 100 of file rate_limit.c.

                                                                {
  rate_limiter_t *limiter = malloc(sizeof(rate_limiter_t));
  if (!limiter) {
    log_error("Failed to allocate rate limiter");
    return NULL;
  }
 
  limiter->backend_data = sqlite_backend_create(db_path);
  if (!limiter->backend_data) {
    free(limiter);
    return NULL;
  }
 
  limiter->ops = &sqlite_backend_ops;
  return limiter;
}

References rate_limiter_s::backend_data, log_error, rate_limiter_s::ops, sqlite_backend_create(), and sqlite_backend_ops.

Referenced by acds_server_init().

rate_limiter_destroy()

void rate_limiter_destroy

(

rate_limiter_t *

limiter

)

Destroy rate limiter and free resources.

Parameters

limiter

Rate limiter instance (NULL-safe)

Definition at line 126 of file rate_limit.c.

                                                   {
  if (!limiter) {
    return;
  }
 
  if (limiter->ops && limiter->ops->destroy) {
    limiter->ops->destroy(limiter->backend_data);
  }
 
  free(limiter);
}

References rate_limiter_s::backend_data, rate_limiter_backend_ops_t::destroy, and rate_limiter_s::ops.

Referenced by acds_server_shutdown(), http_server_destroy(), and http_server_init().

rate_limiter_event_type_string()

const char * rate_limiter_event_type_string

(

rate_event_type_t

event_type

)

Get event type string for logging/database storage.

Parameters

event_type

Event type enum value

Returns

Event type name string (e.g., "session_create", "connection")

Get event type string for logging/database storage.

Helper: Get event type string for logging.

Definition at line 194 of file rate_limit.c.

                                                                         {
  if (event_type >= RATE_EVENT_MAX) {
    return "unknown";
  }
  return event_type_strings[event_type];
}

References RATE_EVENT_MAX.

Referenced by rate_limiter_check().

rate_limiter_prune()

asciichat_error_t rate_limiter_prune	(	rate_limiter_t *	limiter,
		uint32_t	max_age_secs )

Clean up old rate limit events.

Deletes events older than the specified age to prevent unbounded growth. Should be called periodically (e.g., every 5 minutes).

Parameters

limiter	Rate limiter instance
max_age_secs	Delete events older than this (0 = use default 1 hour)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 178 of file rate_limit.c.

                                                                                     {
  ASCII_OTEL_SCOPE(RATE_LIMITER_PRUNE);
  if (!limiter || !limiter->ops || !limiter->ops->cleanup) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid rate limiter");
  }
 
  return limiter->ops->cleanup(limiter->backend_data, max_age_secs);
}

References ASCII_OTEL_SCOPE, rate_limiter_s::backend_data, rate_limiter_backend_ops_t::cleanup, ERROR_INVALID_PARAM, rate_limiter_s::ops, and SET_ERRNO.

rate_limiter_record()

asciichat_error_t rate_limiter_record	(	rate_limiter_t *	limiter,
		const char *	ip_address,
		rate_event_type_t	event_type )

Record a rate limit event.

Should be called after rate_limiter_check() returns allowed=true.

Parameters

limiter	Rate limiter instance
ip_address	IP address string
event_type	Type of event

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 162 of file rate_limit.c.

                                                                                                                     {
  if (!limiter || !limiter->ops || !limiter->ops->record) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid rate limiter");
  }
 
  if (!ip_address) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ip_address is NULL");
  }
 
  if (event_type >= RATE_EVENT_MAX) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid event_type: %d", event_type);
  }
 
  return limiter->ops->record(limiter->backend_data, ip_address, event_type);
}

References rate_limiter_s::backend_data, ERROR_INVALID_PARAM, rate_limiter_s::ops, RATE_EVENT_MAX, rate_limiter_backend_ops_t::record, and SET_ERRNO.

Referenced by check_and_record_rate_limit(), and http_server_dispatch_http3().

rate_limiter_set_sqlite_db()

void rate_limiter_set_sqlite_db	(	rate_limiter_t *	limiter,
		void *	db )

Set SQLite database handle for rate limiter.

For SQLite-backed rate limiters where the database lifecycle is managed externally (e.g., ACDS manages its own database). Must be called after rate_limiter_create_sqlite(NULL).

Parameters

limiter	Rate limiter instance (must be SQLite backend)
db	SQLite database handle

Definition at line 117 of file rate_limit.c.

                                                                   {
  if (!limiter || !limiter->backend_data) {
    return;
  }
 
  // Call the SQLite backend function to set the database handle
  sqlite_backend_set_db(limiter->backend_data, (sqlite3 *)db);
}

References rate_limiter_s::backend_data, and sqlite_backend_set_db().

Referenced by acds_server_init().

Variable Documentation

DEFAULT_RATE_LIMITS

const rate_limit_config_t DEFAULT_RATE_LIMITS[RATE_EVENT_MAX]

extern

Default rate limits for each event type.

Definition at line 33 of file rate_limit.c.

                                                                {
// ACDS discovery server limits
#ifdef NDEBUG
    // Release mode: production limits (144 FPS video, 172 FPS audio)
    [RATE_EVENT_SESSION_CREATE] = {.max_events = 10, .window_secs = 60}, // 10 creates per minute
    [RATE_EVENT_SESSION_LOOKUP] = {.max_events = 30, .window_secs = 60}, // 30 lookups per minute
    [RATE_EVENT_SESSION_JOIN] = {.max_events = 20, .window_secs = 60},   // 20 joins per minute
    [RATE_EVENT_CONNECTION] = {.max_events = 50, .window_secs = 60},     // 50 connections per minute
    [RATE_EVENT_IMAGE_FRAME] = {.max_events = 8640, .window_secs = 60},  // 8640 frames/min = 144 FPS
    [RATE_EVENT_AUDIO] = {.max_events = 10320, .window_secs = 60},       // 10320 packets/min = 172 FPS
    [RATE_EVENT_PING] = {.max_events = 120, .window_secs = 60},          // 120 pings/min = 2 Hz max
    [RATE_EVENT_CLIENT_JOIN] = {.max_events = 10, .window_secs = 60},    // 10 joins per minute
    [RATE_EVENT_CONTROL] = {.max_events = 100, .window_secs = 60},       // 100 control packets/min
    [RATE_EVENT_HTTP_REQUEST] = {.max_events = 120, .window_secs = 60},  // 120 HTTP requests/minute
#else
    // Debug mode: slightly relaxed limits for development/testing (1.5x production limits)
    [RATE_EVENT_SESSION_CREATE] = {.max_events = 15, .window_secs = 60}, // 15 creates per minute
    [RATE_EVENT_SESSION_LOOKUP] = {.max_events = 45, .window_secs = 60}, // 45 lookups per minute
    [RATE_EVENT_SESSION_JOIN] = {.max_events = 30, .window_secs = 60},   // 30 joins per minute
    [RATE_EVENT_CONNECTION] = {.max_events = 75, .window_secs = 60},     // 75 connections per minute
    [RATE_EVENT_IMAGE_FRAME] = {.max_events = 12960, .window_secs = 60}, // 12960 frames/min = 216 FPS
    [RATE_EVENT_AUDIO] = {.max_events = 15480, .window_secs = 60},       // 15480 packets/min = 258 FPS
    [RATE_EVENT_PING] = {.max_events = 180, .window_secs = 60},          // 180 pings/min = 3 Hz
    [RATE_EVENT_CLIENT_JOIN] = {.max_events = 25, .window_secs = 60},    // 25 joins per minute (for testing reconnects)
    [RATE_EVENT_CONTROL] = {.max_events = 150, .window_secs = 60},       // 150 control packets/min
    [RATE_EVENT_HTTP_REQUEST] = {.max_events = 120, .window_secs = 60},  // 120 HTTP requests/minute
#endif
};

Referenced by http_server_init().