0xA — The NULL-TERMINATOR

A single-header, FastAPI-inspired HTTP framework for C. Zero dynamic allocation per request. Multi-threaded by default. No dependencies.

#define OXA_IMPLEMENTATION
#include "0xA.h"

void hello(OxAPI* api, HTTPRequestHeaders* req, int fd) {
    OxA_send_json_response(fd, 200, "{\"message\":\"hello, world\"}");
}

int main(void) {
    OxAPI api = {0};
    int port = 8080;
    OxA_create_api("0.0.0.0", &port, &api);
    OXA_GET(&api, "/", hello);
    OxA_start_listen(&api);
}

---

Features

• Single-header — one #include, one #define OXA_IMPLEMENTATION. No build system changes.
• Multi-threaded — one detached pthread per connection; up to 420 concurrent connections out of the box.
• Zero malloc per request — per-thread bump-pointer arena (Zone 1), slab-allocated connection objects (Zone 2), static I/O ring buffers (Zone 3).
• Route params — :param path segments parsed automatically.
• Route macros — OXA_GET / POST / PUT / PATCH / DELETE for one-liner registration.
• Middleware — global chain + per-route middleware via OxA_route_use().
• Built-in middlewares — logger, request-id injector, require-JSON, require-auth, body size limiter.
• CORS — automatic header injection and OPTIONS preflight handling.
• Rate limiting — per-IP sliding window, no external state.
• Static files — directory mounts with MIME detection.
• Structured errors — OxA_send_error() / OxA_send_error_field() emit consistent JSON error bodies.
• Redirect — OxA_send_redirect() for 301 / 302 / 307 / 308.
• Chunked streaming — OxA_stream_begin/chunk/end for Transfer-Encoding: chunked.
• Server-Sent Events — OxA_sse_begin() / OxA_sse_event().
• Background tasks — OxA_dispatch_task() fire-and-forget detached thread.
• JWT helpers — structural parser (OxA_parse_jwt) + claim accessor (OxA_jwt_get_claim).
• Generic header accessor — OxA_get_request_header() for any standard or custom header.
• Lifecycle hooks — on_start, on_stop, on_connect, on_disconnect, on_request, on_response.
• Custom error handlers — per status code.
• Cookies, forms, query strings — all parsed and accessible by name.
• In-process test client — OxA_test_route() exercises the full middleware + route stack without a real socket.
• OpenAPI 3.0 spec — auto-generated from registered routes, served at /openapi.json. No schema files required.
• Swagger UI — interactive docs at /docs, loaded from the unpkg CDN. Zero extra files.
• Route annotations — OXA_DESCRIBE, OXA_DOC_TAG, OXA_DOC_PATH_PARAM, OXA_DOC_QUERY_PARAM, OXA_DOC_BODY, OXA_DOC_RESPONSES.
• Opt-out — compile with -DAPI_DISABLE_DOCS to strip the feature entirely.
• Socket timeouts — configurable recv/send timeouts.
• User data pointer — attach a database handle or config struct to OxAPI.user_data.

---

Building

0xA has no build-time dependencies beyond a POSIX C11 compiler.

# Compile your app (GCC example)
gcc -O2 -pthread -o server my_server.c

# Or with clang
clang -O2 -pthread -o server my_server.c

Include src/0xA.h from wherever you store it. In one .c file:

#define OXA_IMPLEMENTATION
#include "path/to/0xA.h"

All other .c files that need the types/prototypes:

#include "path/to/0xA.h"

---

Quick Start

#define OXA_IMPLEMENTATION
#include "0xA.h"

/* GET /greet/:name */
void greet(OxAPI* api, HTTPRequestHeaders* req, int fd) {
    const char* name = OxA_get_path_param(req, "name");
    char body[128];
    snprintf(body, sizeof(body), "{\"hello\":\"%s\"}", name ? name : "stranger");
    OxA_send_json_response(fd, 200, body);
}

/* POST /items — requires JSON body */
void create_item(OxAPI* api, HTTPRequestHeaders* req, int fd) {
    if (!req->body) {
        OxA_send_error(fd, 400, "body is required");
        return;
    }
    OxA_send_json_response(fd, 201, req->body);
}

int logger_mw(OxAPI* api, HTTPRequestHeaders* req, int fd) {
    OxA_log_info("-> %s %s", req->method, req->path);
    return 0; /* continue */
}

int main(void) {
    OxAPI api = {0};
    int port = 8080;

    OxA_create_api("0.0.0.0", &port, &api);
    OxA_use(logger_mw, &api);

    OXA_GET(&api,  "/greet/:name", greet);
    OXA_POST(&api, "/items",       create_item);

    OxA_log_info("Listening on :%d", port);
    return OxA_start_listen(&api);
}

---

Examples

Three complete, documented examples live in examples/:

File	What it demonstrates
examples/todo_api.c	CRUD REST API, per-route API-key middleware, rate limiting, CORS, user_data, in-process tests (make test)
examples/realtime.c	SSE event stream, chunked streaming, background task dispatch
examples/jwt_auth.c	JWT login/refresh/logout, RBAC with per-route middleware, cookie-based token invalidation

make run-todo      # build & start the todo API on :8080
make run-realtime  # build & start the realtime demo
make run-jwt       # build & start the JWT auth server
make test          # run the todo_api in-process route tests (no server needed)

Once any server is running, visit http://localhost:8080/docs for the interactive Swagger UI.

---

Documentation

Full API reference and guides: WIKI.md

Topics covered:

• Memory architecture (arena / slab / ring buffers)
• Route registration and path params
• Middleware system (global + per-route)
• Built-in middlewares
• CORS and rate limiting
• Streaming and SSE
• JWT helpers
• Background tasks
• Test client
• OpenAPI 3.0 spec generation and Swagger UI
• Complete function reference

---

License

MIT © 2025 ramsy0dev