Handlers

Handlers are the functions that process HTTP requests and return responses. They contain your application logic.

Handler Signature

Every handler follows the same signature:

using http_handler_t = std::function<http_response_t(const http_request&)>;

The handler receives a read-only http_request and must build and return an http_response_t. The framework sends the response after the handler returns.

---

Inline Handler

Define the handler directly at the route registration point. Best for simple endpoints.

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

app.register_endpoint(
    http_verb_t::get,
    "/hello",
    [](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, "Hello!");
        helpers::finalize_response(res, body);
        return res;
    }
);

---

Named Function

Define the handler as a separate function. Best for complex logic, reuse across routes, or testability.

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

http_response_t list_users(const http_request& req) {
    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;
}

app.register_endpoint(http_verb_t::get, "/users", list_users);

---

Building Responses Manually

You can also build responses from scratch without the helper functions. Use this when you need full control over the response format.

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

[](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;
};

Important: Always call res.prepare_payload() before returning. If you use helpers::finalize_response(), it already calls prepare_payload() internally — do not call it again.

---

The Response Object Methods

res.result(status_code);          // Set HTTP status (http_status_t::ok, ::not_found, etc.)
res.set(field, value);            // Set a header by enum or string name
res.body() = string_content;      // Set the response body
res.prepare_payload();            // Finalize — must be called before returning

---

Built-in Handlers

The framework includes pre-built HTTP handlers for introspection and management. They are in the framework::clients::http::handlers namespace.

Handler	URL	Purpose
get_this_ping	GET /this/ping	Health check — returns pong
get_this_up	GET /this/up	Uptime check
get_this_nodes	GET /this/nodes	List peer nodes in the mesh
get_this_configuration	GET /this/configuration	Show current runtime configuration
patch_this_configuration	PATCH /this/configuration	Update runtime configuration
get_this_cache	GET /this/cache	List cache entries
get_this_cache_by_key	GET /this/cache/:key	Get a specific cache entry
get_this_cache_metrics	GET /this/cache/metrics	Cache metrics
get_this_channels	GET /this/channels	List Pub/Sub channels
get_this_channel_by_name	GET /this/channels/:name	Get a specific channel
get_this_channel_subscriptions	GET /this/channels/:name/subscriptions	Channel subscribers
get_this_watchers	GET /this/watchers	List active watchers
get_this_watchers_nodes	GET /this/watchers/nodes	Node watchers
get_this_watchers_clients	GET /this/watchers/clients	Client watchers
get_this_watchers_channels	GET /this/watchers/channels	Channel watchers
get_this_watchers_cache	GET /this/watchers/cache	Cache watchers
get_this_mailboxes	GET /this/mailboxes	List mailbox queues
get_this_topology	GET /this/topology	Show mesh topology
get_this_logging	GET /this/logging	Show current log configuration
put_this_logging	PUT /this/logging	Update log configuration
get_this_queues	GET /this/queues	List job queues
get_this_queue_by_name	GET /this/queues/:name	Get a specific queue
get_this_queue_metrics	GET /this/queues/:name/metrics	Queue metrics
post_this_queue_pause	POST /this/queues/:name/pause	Pause a queue
post_this_queue_resume	POST /this/queues/:name/resume	Resume a queue
post_this_queue_cancel	POST /this/queues/:name/cancel	Cancel a job by ID
post_this_queue_dispatch	POST /this/queues/:name/dispatch	Dispatch a job via HTTP

These handlers follow a consistent JSON response format. Register them manually via register_endpoint() with the corresponding URLs listed above.