healthz.h File Reference

Standardised readiness and liveness probing for CWIST. More...

#include <cwist/net/http/http.h>
#include <stdbool.h>

Include dependency graph for healthz.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_health_probe
	Result of a single probe. More...

Typedefs
typedef enum cwist_health_status	cwist_health_status_t
	Classification of a subsystem health check.
typedef struct cwist_health_probe	cwist_health_probe_t
	Result of a single probe.
typedef cwist_health_probe_t(*	cwist_health_probe_fn) (void *ctx)
	User-provided probe callback.

Enumerations
enum	cwist_health_status { CWIST_HEALTH_OK , CWIST_HEALTH_DEGRADED , CWIST_HEALTH_FAIL }
	Classification of a subsystem health check. More...

Functions
bool	cwist_healthz_register (const char *name, cwist_health_probe_fn fn, void *ctx)
	Register a custom probe function.
void	cwist_healthz_unregister (const char *name)
	Unregister a previously registered probe.
void	cwist_healthz_run (cwist_health_probe_t *out_probes, size_t max_probes, size_t *out_count, cwist_health_status_t *out_overall)
	Evaluate all probes and return the aggregate status.
void	cwist_app_healthz (cwist_http_response *res)
	Populate an HTTP response with the healthz JSON payload.
void	cwist_app_enable_healthz (struct cwist_app *app)
	Register built-in health check routes on an application.

Detailed Description

Standardised readiness and liveness probing for CWIST.

Provides a cwist_app_healthz endpoint that reports the aggregated health of dependent subsystems (database, io_uring backend, memory).

Definition in file healthz.h.

Typedef Documentation

cwist_health_probe_fn

typedef cwist_health_probe_t(* cwist_health_probe_fn) (void *ctx)

User-provided probe callback.

Definition at line 38 of file healthz.h.

cwist_health_probe_t

typedef struct cwist_health_probe cwist_health_probe_t

Result of a single probe.

cwist_health_status_t

typedef enum cwist_health_status cwist_health_status_t

Classification of a subsystem health check.

Enumeration Type Documentation

cwist_health_status

enum cwist_health_status

Classification of a subsystem health check.

Enumerator
CWIST_HEALTH_OK	Subsystem is healthy.
CWIST_HEALTH_DEGRADED	Subsystem is functional but impaired.
CWIST_HEALTH_FAIL	Subsystem is down or unreachable.

Definition at line 24 of file healthz.h.

Function Documentation

cwist_app_enable_healthz()

void cwist_app_enable_healthz

(

struct cwist_app *

app

)

Register built-in health check routes on an application.

Adds /healthz, /live, and /ready GET routes.

Parameters

app	Application to register routes on.

Definition at line 2249 of file app.c.

cwist_app_healthz()

void cwist_app_healthz

(

cwist_http_response *

res

)

Populate an HTTP response with the healthz JSON payload.

Status mapping:

• 200 OK when overall == CWIST_HEALTH_OK
• 503 Service Unavailable when overall == CWIST_HEALTH_FAIL or DEGRADED

JSON shape:

{"status":"ok","probes":[{"name":"database","status":"ok"},...]}

Parameters

res	Response to populate.

Populate an HTTP response with the healthz JSON payload.

Runs all registered probes and writes a JSON body with an overall "status" field and a "probes" array of per-probe name, status, and optional message. The response Content-Type is set to application/json.

Parameters

res	Response to fill; NULL is a no-op. The body and headers are (re)assigned on success.

Definition at line 168 of file healthz.c.

References cwist_http_response::body, cap, count, CWIST_HEALTH_DEGRADED, CWIST_HEALTH_FAIL, CWIST_HEALTH_OK, CWIST_HEALTHZ_MAX_PROBES, cwist_healthz_run(), cwist_http_header_add(), CWIST_HTTP_OK, CWIST_HTTP_SERVICE_UNAVAILABLE, cwist_json_add_string(), cwist_json_begin_array(), cwist_json_begin_object(), cwist_json_builder_create(), cwist_json_builder_destroy(), cwist_json_end_array(), cwist_json_end_object(), cwist_json_get_raw(), cwist_sstring_assign(), cwist_http_response::headers, and cwist_http_response::status_code.

cwist_healthz_register()

bool cwist_healthz_register	(	const char *	name,
		cwist_health_probe_fn	fn,
		void *	ctx
	)

Register a custom probe function.

Probes are evaluated in registration order when /healthz is requested.

Parameters

name	Probe name exposed in the JSON response.
fn	Probe callback.
ctx	Opaque context forwarded to fn.

Returns

true on success.

Register a custom probe function.

If a probe with the same name is already active, its function and context are replaced in place. Otherwise the probe is appended to the registry.

Parameters

name	Probe name; must be non-NULL and outlive the registration.
fn	Probe function; must be non-NULL.
ctx	Opaque context passed to fn on each evaluation.

Returns

true on success, false if name or fn is NULL or the registry is full.

Definition at line 45 of file healthz.c.

References cap, and CWIST_HEALTHZ_MAX_PROBES.

cwist_healthz_run()

void cwist_healthz_run	(	cwist_health_probe_t *	out_probes,
		size_t	max_probes,
		size_t *	out_count,
		cwist_health_status_t *	out_overall
	)

Evaluate all probes and return the aggregate status.

Parameters

out_probes	[out] Array of probe results (caller provides storage).
max_probes	Capacity of out_probes.
out_count	[out] Number of probes written.
out_overall	[out] OK only if every probe is OK; FAIL if any probe is FAIL; otherwise DEGRADED.

Evaluate all probes and return the aggregate status.

Probes are evaluated in registration order. The overall status is FAIL if any probe reports FAIL, DEGRADED if at least one reports DEGRADED and none report FAIL, and OK otherwise.

Parameters

out_probes	Optional array receiving per-probe results; at most max_probes entries are written.
max_probes	Capacity of out_probes.
out_count	Optional output receiving the number of active probes evaluated.
out_overall	Optional output receiving the aggregated status.

Definition at line 130 of file healthz.c.

References cap, count, CWIST_HEALTH_DEGRADED, CWIST_HEALTH_FAIL, CWIST_HEALTH_OK, and cwist_health_probe::status.

Referenced by cwist_app_healthz().

cwist_healthz_unregister()

void cwist_healthz_unregister

(

const char *

name

)

Unregister a previously registered probe.

Unregister a previously registered probe.

Marks every active entry with the given name as inactive; inactive entries are skipped by cwist_healthz_run and their slots may be reused by cwist_healthz_register. The name and function pointers are not cleared.

Parameters

name	Probe name to remove; NULL is a no-op.

Definition at line 88 of file healthz.c.

References cap.