cinatra Documentation

Cinatra supports an aspect-oriented approach (similar to middleware) where you can intercept requests before and after the main handler.

An aspect is a struct that implements:

• bool before(coro_http_request& req, coro_http_response& res): Executed before the handler. Returning false stops the chain and allows the aspect to modify the response (e.g., returning an error status).
• bool after(coro_http_request& req, coro_http_response& res): Executed after the handler.

Aspects can also pass data to the handler using req.set_aspect_data(data) and req.get_aspect_data().

Pass aspects as additional arguments to set_http_handler. They are executed in the order they are provided.

struct log_t {
    bool before(coro_http_request& req, coro_http_response& res) {
        std::cout << "before log" << std::endl;
        return true;
    }
    bool after(coro_http_request& req, coro_http_response& res) {
        std::cout << "after log" << std::endl;
        return true;
    }
};

// Usage in server
server.set_http_handler<GET, POST>("/aspect", [](coro_http_request& req, coro_http_response& res) {
    res.set_status_and_content(status_type::ok, "hello world");
}, log_t{});

The coro_http_client uses a global io_context pool (the "thread pool"). By default, the number of threads in this pool equals the number of CPU cores. You can adjust this using coro_io::get_global_executor(pool_size).

Thread Safety Warning

A coro_http_client instance is NOT thread-safe. You must ensure only one thread calls a specific client instance at a time.

To achieve concurrency, use one of these two patterns:

1. Multiple Clients: Create a pool of coro_http_client objects. The global thread pool will distribute these clients across available threads using a round-robin approach.
2. Multiple Coroutines: Use multiple coroutines to make requests. Each coroutine will execute within a thread from the global pool.

Concurrency Example (Multiple Clients)

std::vector<std::shared_ptr<coro_http_client>> clients;
std::vector<async_simple::coro::Lazy<resp_data>> futures;
for (int i = 0; i < 10; ++i) {
  auto client = std::make_shared<coro_http_client>();
  futures.push_back(client->async_get("http://www.baidu.com/"));
  clients.push_back(client);
}

auto out = co_await async_simple::coro::collectAll(std::move(futures));

Aspects in cinatra allow you to intercept HTTP requests and responses using before and after methods. An aspect is a class that implements one or both of these methods:

• bool before(coro_http_request &req, coro_http_response &res): Executed before the business logic. If it returns false, the subsequent handler is skipped. If you return false, you must manually set the response status and content using res.set_status_and_content.
• bool after(coro_http_request &req, coro_http_response &res): Executed after the business logic.

Aspects can also be used to pass data to the handler using req.set_aspect_data(value) and retrieving it via req.get_aspect_data().

To apply aspects, pass them as additional arguments to server.set_http_handler<METHOD>(path, handler, aspect1, aspect2, ...).

struct log_t {
  bool before(coro_http_request &req, coro_http_response &res) {
    std::cout << "before log" << std::endl;
    return true;
  }

  bool after(coro_http_request &req, coro_http_response &res) {
    std::cout << "after log" << std::endl;
    res.add_header("aaaa", "bbcc");
    return true;
  }
};

struct get_data {
  bool before(coro_http_request &req, coro_http_response &res) {
    req.set_aspect_data("hello world");
    return true;
  }
};

// Usage
server.set_http_handler<GET>(
    "/get",
    [](coro_http_request &req, coro_http_response &resp) {
      auto val = req.get_aspect_data();
      resp.set_status_and_content(status_type::ok, "ok");
    },
    log_t{}, get_data{} // Applying multiple aspects
);

Labels are optional key-value pairs used to categorize metrics. The keys are defined at the time of metric creation and are immutable. The values can be either static or dynamic:

Static Labels

Defined at creation time with both keys and values. When using the metric, you must provide the exact same values. Example: {{ "method", "GET" }, { "url", "/" }}

Dynamic Labels

Only the keys are defined at creation time. The values are provided at runtime when recording the metric. Example: Keys {"method", "url"} can be used with runtime values like {"GET", "/"} or {"POST", "/test"}.

Warning: When using dynamic labels, ensure the cardinality (the number of unique label value combinations) is finite. If the number of unique values is infinite, the internal map will grow indefinitely, leading to memory exhaustion.

No Labels

If no labels are provided during creation, the metric maintains a single internal counter.

Use metric_manager_t to centrally manage multiple metrics. You can register metrics as either static or dynamic.

Best Practice: Create and register all metrics at the start of your application. This allows you to retrieve metric objects by name using lock-free static methods later.

Important: You must use matching interfaces for registration and retrieval. If you register a metric using register_metric_static, you must retrieve it using get_metric_static. Mixing static and dynamic interfaces for the same metric will cause an exception.

auto c = std::make_shared<counter_t>("qps_count", "qps help");
auto g = std::make_shared<gauge_t>("fd_count", "fd count help");
// Registering as static
default_metric_manager::register_metric_static(c);
default_metric_manager::register_metric_static(g);

c->inc();

// Retrieving as static
auto m = default_metric_manager::get_metric_static("qps_count");
CHECK(m->as<counter_t>()->value() == 1);

cinatra supports Aspect-Oriented Programming (AOP) to implement cross-cutting concerns like logging or authentication.

An aspect is a struct that implements before and after methods:

• bool before(coro_http_request& req, coro_http_response& res): Executed before the main handler. Return false to abort the request (e.g., for validation failures).
• bool after(coro_http_request& req, coro_http_response& res): Executed after the main handler.

You can also pass data from an aspect to the handler using req.set_aspect_data() and retrieving it via req.get_aspect_data().

To use aspects, pass them as additional arguments to set_http_handler after the handler function.

#include "cinatra.hpp"
using namespace cinatra;

// Example Aspect: Logging
struct log_t {
	bool before(coro_http_request& req, coro_http_response& res) {
		std::cout << "before log" << std::endl;
		return true;
	}

	bool after(coro_http_request& req, coro_http_response& res) {
		std::cout << "after log" << std::endl;
		return true;
	}
};

// Example Aspect: Validation
struct check {
	bool before(coro_http_request& req, coro_http_response& res) {
		if (req.get_header_value("name").empty()) {
			res.set_status_and_content(status_type::bad_request);
			return false;
		}
		return true;
	}

	bool after(coro_http_request& req, coro_http_response& res) {
		return true;
	}
};

int main() {
	coro_http_server server(std::thread::hardware_concurrency(), 8080);
	// Registering handler with aspects
	server.set_http_handler<GET, POST>("/aspect", [](coro_http_request& req, coro_http_response& res) {
		res.set_status_and_content(status_type::ok, "hello world");
	}, check{}, log_t{});

	server.sync_start();
	return 0;
}