Request & Response

The Request Object

The http_request struct gives you access to everything the client sent: the raw HTTP message, parsed JSON body, path and query parameters, and the underlying connection.

using namespace framework;
using namespace framework::clients::http;

struct http_request {
    std::shared_ptr<state::instance> state_;    // The app state (registries, config, etc.)
    http_connection& http_connection_;          // The underlying TCP/HTTP connection
    http_params http_params_;                   // Path and query parameters from the route
    const http_request_t& raw_request_;         // The raw Boost.Beast HTTP request
    std::optional<value> body_;                 // Parsed JSON body (if Content-Type is JSON)
};

state_ — App state

Access to the shared state instance. Use this to interact with registries, cache, jobs, etc. from within a handler.

auto& cache = req.state_->of_cache();
auto& clients = req.state_->of_clients();

http_connection_ — The connection

The underlying HTTP connection (framework::clients::http_connection). Provides access to JWT state, connection metadata, and the router.

auto& jwt = req.http_connection_.get_jwt();       // support::auth::jwt&
auto& metrics = req.http_connection_.get_metrics(); // support::session_metrics&
auto* router = req.http_connection_.get_router();   // http::router*

http_connection methods:

Method	Return Type	Description
get_id()	boost::uuids::uuid&	Connection UUID
get_jwt()	support::auth::jwt&	JWT state for this connection
get_router()	http::router*	Router for this connection
get_metrics()	support::session_metrics&	Connection metrics
get_ip()	std::string	Client IP address
get_port()	uint16_t	Client port

http_params_ — Route parameters

Contains path parameters extracted from the matched route and query string parameters.

Path Parameters:

Path parameters are extracted using the router's named parameter syntax (:param). They are stored by name in unordered_map<string, string>.

auto& params = req.http_params_.path_;
// For route "/users/:id" matching "/users/42":
// params["id"] = "42"

// For route "/posts/:post_id/comments/:comment_id":
// params["post_id"] = "5", params["comment_id"] = "12"

See Route Patterns for the full syntax reference.

Query Parameters:

Query string parameters parsed from the URL. Stored as unordered_map<string, string>.

auto& query = req.http_params_.query_;
// e.g., for "/users?page=2&sort=name":
// query["page"] = "2"
// query["sort"] = "name"

raw_request_ — Raw Boost.Beast request

Access the unmodified HTTP request. Useful for reading headers, the raw body, or the HTTP method.

auto& raw = req.raw_request_;
auto method = raw.method();           // http::verb::get, http::verb::post, etc.
auto target = raw.target();           // The raw request target string
auto header = raw[boost::beast::http::field::content_type];  // use [] instead of .at() to avoid throw on missing header
auto raw_body = raw.body();           // The raw body string

body_ — Parsed JSON body

If the request's Content-Type is application/json, the framework automatically parses the body into a boost::json::value. Always check has_value() before accessing.

if (req.body_.has_value()) {
    boost::json::value body = req.body_.value();
    auto name = body.as_object().at("name").as_string();
}

---

The Response Object

The response type is boost::beast::http::response<boost::beast::http::string_body>. You build it in your handler and return it.

using namespace framework;
using namespace framework::clients::http;

http_response_t res;

// Set status
res.result(http_status_t::ok);         // 200
res.result(http_status_t::created);    // 201
res.result(http_status_t::no_content); // 204
res.result(http_status_t::bad_request);// 400
res.result(http_status_t::not_found);  // 404
res.result(http_status_t::internal_server_error); // 500

// Set headers
res.set(http_field_t::content_type, "application/json");
res.set("X-Request-Id", "abc123");

// Set body
res.body() = R"({"message":"success"})";

// Finalize — calculates Content-Length
res.prepare_payload();

return res;

Building a response from scratch

[](const auto& req) -> http_response_t {
    http_response_t res;
    res.result(http_status_t::ok);
    res.set(http_field_t::content_type, "application/json");
    res.body() = R"({"status":200,"message":"ok"})";
    res.prepare_payload();
    return res;
};

---

Using Response Helpers

The framework provides helpers to build consistent JSON responses with a standard envelope format.

using namespace framework;
using namespace framework::clients::http;

auto res = helpers::make_base_http_response(req, http_status_t::ok);

auto body = helpers::make_base_http_payload(200, "Success message");
body["extra_data"] = some_json_value;

helpers::finalize_response(res, body);
return res;

The resulting JSON envelope:

{"status": 200, "message": "Success message", "extra_data": ...}

Helper	Purpose
make_base_http_response(req, status)	Creates a response with CORS headers from the request.
make_base_http_payload(status, message)	Creates a {"status": N, "message": "..."} JSON object.
finalize_response(res, body)	Sets the body, content-type, and calls prepare_payload().
make_node_object(id, host, nodes_port, clients_port)	Creates a JSON object describing a mesh node.
make_session_object(id, node_id, host, ...)	Creates a JSON object describing a client session.
make_metrics_object(metrics)	Creates a JSON object from session_metrics.