slweb.h
lib/web-server-technology/native/include/slweb.h · 185 line(s) · c
/*
* lib/web-server-technology/native/include/slweb.h
*
* SLeeLa Web Server Technology -- native C11 library (public C ABI).
*
* This is the reusable, dependency-free C core of the web-server-technology
* subsystem. It is the library form of the model the standalone server builds
* on (see the web-server-technology native sources): the two-sided interface
*
* Side 1 -- a program goes to a domain and then a meme (one response unit);
* Side 2 -- a domain envelops many programs via subjects/warrants for causes,
* Scientist-gated,
*
* plus the production-hardening and CPU keep-warm primitives. It ships no
* sockets and no HTTP wire handling: it is the decision/model layer that a
* transport (the server, a test, or another embedder) drives. The adjacent
* C++17 facade in ../cpp wraps this same ABI with RAII types.
*
* Mirrors the design of lib/sleela-sql (native C core + cpp facade).
*/
#ifndef SLEELA_SLWEB_H
#define SLEELA_SLWEB_H
#include <stddef.h>
#ifdef __cplusplus
extern "C" {
#endif
#define SLWEB_MAX_NAME 128
#define SLWEB_MAX_PATH 1024
/* ---- status codes ---------------------------------------------------- */
typedef enum {
SLWEB_OK = 0,
SLWEB_ERR_ARG = -1, /* bad argument */
SLWEB_ERR_OOM = -2, /* allocation failed */
SLWEB_ERR_NOTFOUND = -3, /* no match / no such program */
SLWEB_ERR_DENIED = -4, /* a gate refused (scientist/auth/rate) */
SLWEB_ERR_RANGE = -5 /* value outside the allowed range */
} slweb_status;
/* ================================================================== */
/* Side 2 -- envelopment */
/* ================================================================== */
typedef enum {
SLWEB_PROGRAM_MEME = 0, /* a single fixed response (the "meme") */
SLWEB_PROGRAM_STATIC = 1, /* a document-root subtree */
SLWEB_PROGRAM_SQL = 2 /* a /db-style SQL surface over a table dir */
} slweb_program_kind;
/* Opaque envelopment handle: a domain plus its programs and warrants. */
typedef struct slweb_envelopment slweb_envelopment;
/* Create an empty envelopment for a domain (NULL domain => ""). */
slweb_envelopment *slweb_env_new(const char *domain);
/* Release an envelopment. Safe on NULL. */
void slweb_env_free(slweb_envelopment *env);
/* The two gates. Side 2 only ACTIVATES with both set and >=1 warrant. */
void slweb_env_set_enabled(slweb_envelopment *env, int enabled);
void slweb_env_set_scientist(slweb_envelopment *env, int scientist);
int slweb_env_enabled(const slweb_envelopment *env);
int slweb_env_scientist(const slweb_envelopment *env);
/* Register a program. `mount` is the owned path prefix (e.g. "/lab"). For
* SQL, `resource` is the table directory and `writable` gates mutations; for
* static, `resource` is the document root; for meme, `resource` is the body.
* Returns SLWEB_OK or an error (duplicate name, bad arg). */
slweb_status slweb_env_add_program(slweb_envelopment *env, const char *name,
slweb_program_kind kind, const char *mount,
const char *resource, int writable);
/* Register a warrant: a cause served for a subject (host, "*" = any) with an
* optional path gate, activating a named program. `enabled` nonzero to arm. */
slweb_status slweb_env_add_warrant(slweb_envelopment *env, const char *cause,
const char *subject, const char *path_prefix,
const char *program, int enabled);
size_t slweb_env_program_count(const slweb_envelopment *env);
size_t slweb_env_warrant_count(const slweb_envelopment *env);
/* Is envelopment usable? (enabled AND scientist AND >=1 warrant). */
int slweb_env_active(const slweb_envelopment *env);
/*
* Resolve (host, path) to a program using longest-matching-path-prefix (ties
* break by declaration order). On a match returns SLWEB_OK and fills:
* out_program : the matched program name (buffer >= SLWEB_MAX_NAME),
* out_cause : the matched warrant's cause (buffer >= SLWEB_MAX_PATH),
* out_kind : the program kind.
* Returns SLWEB_ERR_NOTFOUND if nothing matches (caller falls back to Side 1),
* or SLWEB_ERR_DENIED if envelopment is not active.
*/
slweb_status slweb_env_resolve(const slweb_envelopment *env, const char *host,
const char *path, char *out_program,
char *out_cause, slweb_program_kind *out_kind);
/* Human-readable program-kind name ("meme"/"static"/"sql"). */
const char *slweb_program_kind_name(slweb_program_kind k);
/* ================================================================== */
/* Hardening -- rate limiting + write authorization */
/* ================================================================== */
/* Opaque sliding-window rate limiter (per-peer + global). */
typedef struct slweb_rate slweb_rate;
/* Create a limiter: per_peer / global caps per `window_ms` (0 = that dimension
* disabled). Returns NULL on OOM. */
slweb_rate *slweb_rate_new(unsigned per_peer_max, unsigned global_max,
unsigned window_ms);
void slweb_rate_free(slweb_rate *r);
int slweb_rate_enabled(const slweb_rate *r);
/* Record a request from `peer` at monotonic time `now_ms` and report whether
* it is admitted (1) or rejected (0). Rejected requests are not counted. */
int slweb_rate_allow(slweb_rate *r, const char *peer, unsigned long long now_ms);
/* Drop aged-out per-peer windows (bounds memory). */
void slweb_rate_sweep(slweb_rate *r, unsigned long long now_ms);
/*
* Constant-time string equality (independent of first-mismatch position).
* Returns 1 if equal, 0 otherwise.
*/
int slweb_constant_time_equals(const char *a, const char *b);
/*
* Authorize a write: if `token` is NULL/empty no auth is required (returns 1).
* Otherwise `authorization_header` must be "Bearer <token>" (scheme compared
* case-insensitively; credential compared in constant time). Returns 1 if
* authorized, 0 otherwise.
*/
int slweb_write_authorize(const char *token, const char *authorization_header);
/*
* Effective client IP. If `peer_ip` is in `trusted_proxies` (an array of
* `n_proxies` C strings) and `forwarded_for` is non-empty, the left-most
* forwarded client is returned; otherwise `peer_ip`. Prevents spoofing by
* non-proxy peers. Writes up to `out_cap` bytes (NUL-terminated) to `out`.
*/
slweb_status slweb_client_ip(const char *peer_ip, const char *forwarded_for,
const char *const *trusted_proxies, size_t n_proxies,
char *out, size_t out_cap);
/* ================================================================== */
/* CPU keep-warm idle floor -- band math (no threads) */
/* ================================================================== */
/*
* The keep-warm policy, as pure math so it can be reused and tested without
* spawning threads. The live threaded controller lives in the server
* (web-server-technology/native/cpu_warmer.*); this is the band/target model.
*/
typedef struct {
int enabled; /* on by default when built by slweb_warm_default */
unsigned floor_pct; /* lower edge of the per-core band */
unsigned ceiling_pct; /* upper edge of the per-core band */
unsigned max_cores; /* clamp for warmer threads (1..16) */
unsigned window_ms; /* control window */
} slweb_warm;
/* A default keep-warm policy: ON, 11%-14%, up to 16 cores, 200ms window. */
slweb_warm slweb_warm_default(void);
/* Clamp a policy into the in-contract range (floor 1..90, ceiling floor..95,
* cores 1..16, window 50..2000). Returns the corrected policy. */
slweb_warm slweb_warm_sanitize(slweb_warm w);
/* The controller's target (midpoint of the band), as a percentage. */
double slweb_warm_target_pct(slweb_warm w);
/* Detected online CPU count clamped to [1, max_cores] (and to [1,16]). */
unsigned slweb_warm_core_count(unsigned max_cores);
/* Library version string, e.g. "1.0.0". */
const char *slweb_version(void);
#ifdef __cplusplus
}
#endif
#endif /* SLEELA_SLWEB_H */