Request Lifecycle

Understanding how a request travels through the framework will help you write better services. Here is the journey of an HTTP request from the moment it arrives.

Client → Listener → Kernel → Router → Gate → Validator → Handler → Response

1. Listener Accepts the Connection

The framework runs a TCP listener on the configured HTTP port. When a client connects, the listener accepts the socket and hands it off to the HTTP kernel.

2. Kernel Reads the Request

The HTTP kernel reads the incoming bytes and parses them into a http_request_t (Boost.Beast request). This includes the method, path, headers, and body. The kernel also parses the JSON body and query parameters.

3. Router Matches the Route

The kernel passes the parsed request to the router via router::try_route(). The router matches the request path against all registered route patterns. The match result includes a pointer to the matched route and extracted path parameters:

auto match = router.try_route(verb, path);
// match->params_ is an unordered_map<string, string>

Routes are stored as route objects with an optional gate, validator, and auth flag:

struct route {
    std::string path_;
    http_verb_t http_verb_;
    http_handler_t http_handler_;
    http_validator_t http_validator_ = nullptr;
    http_gate_t http_gate = nullptr;
    bool requires_auth_ = false;
};

4. Gate & Validator Run

If the matched route has requires_auth_ set to true, the JWT is verified first. If a gate function is set, it runs — gates check authorization and return false to reject (HTTP 403). If a validator is set, it runs — validators check input and can return error messages (HTTP 422).

5. Handler Processes the Request

The handler is your function — the business logic. It receives a http_request and returns an http_response_t:

app.register_endpoint(
    http_verb_t::get,
    "/users",
    [](const http_request& req) -> http_response_t {
        auto res = helpers::make_base_http_response(req, http_status_t::ok);
        auto body = helpers::make_base_http_payload(200, "ok");
        body["data"] = boost::json::parse(R"([{"id":1,"name":"Alice"}])");
        helpers::finalize_response(res, body);
        return res;
    }
);

6. Response is Sent

After the handler returns, CORS headers are injected into the response. The kernel then sends the response back to the client. The connection is either kept alive or closed, depending on the HTTP version and headers.

---

The same general flow applies to WebSocket and mesh node messages, with protocol-specific kernels:

• WebSocket: The WebSocket kernel reads FlatBuffers-encoded messages, matches the opcode to a registered handler, runs quota checks, and invokes the handler. The handler returns a message_offset_t which the kernel encodes and sends back.
• Mesh (inter-node): The node kernel processes binary frames over TLS-encrypted connections. It routes by opcode (identify, publish, cache operations, gossip, Raft, etc.) using the registered node handlers.