CST-agent/include/cst_http.h

#ifndef CST_HTTP_H
#define CST_HTTP_H

/* A small HTTP/1.1 server for the built-in WebUI (src/http_srv.c).
 *
 * Only what a local single-page app needs: exact-match routes, keep-alive,
 * fixed-length bodies and chunked streaming responses (SSE). No TLS, no
 * HTTP/2, no chunked *request* bodies, no CGI. Every connection is served
 * by its own thread; a handler may keep the connection as long as it wants
 * (that is how the event stream works). */

#include "cst_net.h"

#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct cst_http_conn cst_http_conn_t;

typedef struct {
  char method[8];  /* GET / POST / DELETE ... */
  char path[1024]; /* percent-decoded, without the query string */
  char query[1024]; /* raw, without '?' */
  const char *body; /* NUL-terminated; may hold binary bytes */
  size_t body_len;
  /* Headers of interest, NULL when absent (pointers into the request). */
  const char *authorization;
  const char *cookie;
  const char *origin;
  const char *host;
  const char *content_type;
  const char *user_agent;
  int keep_alive;
} cst_http_req_t;

/* 0 = handled (a response was sent), -1 = not found (the server replies). */
typedef int (*cst_http_fn)(cst_http_conn_t *c, void *ud);

typedef struct {
  const char *method; /* "*" matches any */
  const char *path;   /* exact; "*" = fallback (try last) */
  cst_http_fn fn;
  void *ud;
  int auth;         /* ask the auth hook before the handler */
  size_t max_body;  /* request body cap; 0 = server default */
} cst_http_route_t;

typedef struct {
  const char *host; /* NULL/"" = 127.0.0.1 */
  int port;         /* 0 = pick a free port */
  size_t max_body;  /* default 1 MiB */
  int max_conn;     /* default 32 */
  int read_timeout_ms; /* waiting for the request headers (default 15000) */
  int idle_timeout_ms; /* keep-alive pause between requests (default 60000) */
  const cst_http_route_t *routes;
  int nroutes;
  /* 0 = allow, -1 = the server answers 401 before the handler runs. */
  int (*auth)(const cst_http_req_t *req, void *ud);
  void *auth_ud;
  /* One line per request, e.g. "GET /api/state -> 200". */
  void (*on_log)(const char *line, void *ud);
  void *log_ud;
} cst_http_opts_t;

typedef struct cst_http_server cst_http_server_t;

/* Start listening. NULL on failure with a reason in err. */
cst_http_server_t *cst_http_start(const cst_http_opts_t *o, char *err,
                                  size_t err_sz);
int cst_http_port(const cst_http_server_t *s);
/* Non-zero once stop() was called: long-lived handlers must return. */
int cst_http_stopping(const cst_http_server_t *s);
/* Close the listener and every connection, then wait for the threads. */
void cst_http_stop(cst_http_server_t *s);
void cst_http_free(cst_http_server_t *s);

/* --- inside a handler --- */
const cst_http_req_t *cst_http_request(cst_http_conn_t *c);
int cst_http_send(cst_http_conn_t *c, int status, const char *ctype,
                  const void *body, size_t n);
int cst_http_send_str(cst_http_conn_t *c, int status, const char *ctype,
                      const char *s);
/* json may be NULL (then "null" is sent); it is copied, not owned. */
int cst_http_send_json(cst_http_conn_t *c, int status, const char *json);
/* {"error":"..."} */
int cst_http_send_err(cst_http_conn_t *c, int status, const char *msg);
/* True once a response (or stream) began for this request. */
int cst_http_sent(const cst_http_conn_t *c);

/* Chunked response: begin(), any number of write()s, end(). */
int cst_http_stream_begin(cst_http_conn_t *c, const char *ctype);
int cst_http_stream_write(cst_http_conn_t *c, const void *data, size_t n);
int cst_http_stream_end(cst_http_conn_t *c);

/* Query parameter, percent-decoded ('+' = space). 0 when found. */
int cst_http_query(const cst_http_req_t *req, const char *key, char *out,
                   size_t out_sz);

#ifdef __cplusplus
}
#endif

#endif /* CST_HTTP_H */