typename Context = no_context

Per-connection state type. When set to anything other than no_context, the session creates one Context (via std::make_shared) for every accepted TCP connection and keeps it alive across all keep-alive requests on that connection. Handlers opt in through leading parameters of type Context&, Context const& or std::shared_ptr<Context>; handlers without such a parameter are unaffected. The default alias, http, uses no_context and creates nothing per connection.

typename Stream = boost::beast::tcp_stream

The connection stream type. boost::beast::tcp_stream for plain HTTP (the default); session::tls_stream from <boost/taar/session/https.hpp> for HTTPS, where the boost::taar::server::tls acceptor performs the handshake before handing the stream over.

basic_http();

void set_method_not_allowed(bool enabled);

Enabled by default.

Only routes whose matcher is a conjunction of one target == ... and method == ... constraints contribute; opaque or negated matchers neither cause a 405 nor appear in Allow.

void set_head_from_get(bool enabled);

Enabled by default.

The handler runs with the original HEAD request and only the response header is written, so Content-Length reflects the GET body. Handlers producing a message_generator write what they produce; a streaming handler's chunked header is sent without chunks. GET routes list HEAD in Allow.

void set_response_filter(unspecified filter);

Applies to handler responses, interceptor rejections, soft-error responses, the stock 404 and the header of chunked responses; raw handlers that return a message_generator are opaque and bypass it. Use it for CORS (taar::cors::response_filter()), a Server header, or security headers.

void set_date_header(bool enabled);

Enabled by default.

Applies wherever the response filter does (handler responses, interceptor rejections, soft-error and protocol-error answers, 404/405, 408, 304 and HEAD responses, the header of chunked responses) and runs after the filter, so a Date set by the handler or the filter is kept. A message_generator is opaque and written as produced. The value is formatted at most once per second per thread.

void set_idle_timeout(std::chrono::steady_clock::duration timeout);

Expiry closes the connection silently. Default 60 seconds; zero disables it.

void set_header_timeout(std::chrono::steady_clock::duration timeout);

Expiry answers 408 Request Timeout with Connection: close (through the response filter) and closes. Default 30 seconds; zero disables it.

void set_body_timeout(std::chrono::steady_clock::duration timeout);

Expiry answers 408 Request Timeout and closes; a streaming handler sees an exception carrying beast::error::timeout, which the default soft error handler answers with 408. Body reads are shielded from shutdown, so this also bounds how long an upload stalled by its client can hold up a graceful shutdown. Default 60 seconds; zero disables it.

void set_send_timeout(std::chrono::steady_clock::duration timeout);

Expiry closes the connection. Only time spent in a write counts: neither the handler's execution nor the time a streaming generator takes between chunks does. Default 60 seconds; zero disables it.

void set_request_header_limit(std::uint32_t limit);

void set_request_body_limit(boost::optional< std::uint64_t > limit);

basic_http(basic_http const &) = delete;

basic_http(basic_http &&) = default;

basic_http & operator=(basic_http const &) = delete;

basic_http & operator=(basic_http &&) = default;

~basic_http() = default;

awaitable< void > 
operator()(boost::asio::ip::tcp::socket socket, 
           cancellation_signals & signals);

Called by boost::taar::server::tcp for every accepted socket. Owns the socket, parses request headers, dispatches to matching handlers, writes responses, honours keep-alive, and terminates on cancellation, peer close, or after a non-keep-alive response. The session runs on the socket's executor (the connection strand when called by the server).

awaitable< void > operator()(Stream stream, cancellation_signals & signals);

Used by boost::taar::server::tls after the handshake, and by any transport that builds its own stream (Stream is the class template parameter, boost::beast::tcp_stream by default). On exit a TLS stream receives close_notify before the TCP shutdown.

template<typename MatcherType, typename RequestHandler> 
  auto register_request_handler(MatcherType &&, RequestHandler);

template<typename MatcherType, typename RequestHandler> 
  auto register_request_handler(MatcherType && matcher, 
                                RequestHandler request_handler);

Routes are evaluated in registration order on every request. The first matcher that returns true wins, the corresponding handler runs, and its response is written back to the client.

The handler may be:

template<typename Operand, typename RequestHandler> 
  auto install_handler(Operand operand, RequestHandler request_handler);

template<typename MatcherType, typename RequestHandler, 
         typename FirstObserver, typename... Observers> 
  auto register_request_handler(MatcherType && matcher, 
                                RequestHandler request_handler, 
                                FirstObserver && first_observer, 
                                Observers &&... observers);

Each trailing observer is invoked once, at registration time, with (matcher::operand const&, RequestHandler const&), before the route is installed. Documentation generators use this to record the route's matcher metadata and the handler's parameters:

session.register_request_handler(
    method == http::verb::get && target == "/users/{id}",
    taar::handler::rest(&get_user, taar::handler::path_arg("id")),
    openapi.describe("Fetch a user"));

template<typename MatcherType, typename ObjectType, typename ResultType, 
         typename... ArgsType> 
  auto register_request_handler(MatcherType && matcher, 
                                ResultType(ObjectType::*)(ArgsType...) memfn, 
                                ObjectType * object);

template<typename MatcherType, typename ObjectType, typename ResultType, 
         typename... ArgsType> 
  auto register_request_handler(MatcherType && matcher, 
                                ResultType(ObjectType::*)(ArgsType...) const memfn, 
                                ObjectType const * object);

template<typename MatcherType, typename RawHandler> 
  auto register_raw_handler(MatcherType && matcher, RawHandler raw_handler);

Used for protocol upgrades such as WebSocket. On a match the handler receives the parsed request header, the underlying stream (a plain boost::beast::tcp_stream, or the plain boost::beast::ssl_stream<boost::beast::tcp_stream> named session::tls_stream for an https session), and the flat_buffer holding any bytes already read past the header. The session performs no further I/O on the stream and ends the session as soon as the handler returns. The stream's default completion token is Asio's, as is that of a beast::websocket::stream<beast::tcp_stream> built on it: pass a token such as taar::use_awaitable explicitly.

The handler signature must be compatible with:

awaitable<void>(
    matcher::context const& context,
    boost::beast::http::request<boost::beast::http::empty_body>&& request,
    Stream&& stream,
    boost::beast::flat_buffer&& buffer,
    cancellation_signals& signals)

	Note
	boost::beast::flat_buffer is value-semantic. Passing it directly to asio::async_read_until / asio::async_read would read into a copy rather than the buffer itself. Pair the buffer with beast::websocket::stream::async_accept (the natural use case) or drain pipelined bytes into a std::string and use boost::asio::dynamic_buffer for further reads.

template<typename Interceptor> void add_interceptor(Interceptor interceptor);

Interceptors run in registration order right after the request header is parsed and validated: before a route is selected, before the 405/404 answers and HEAD-from-GET handling, before any body byte is read, and for raw handlers too. The callable takes leading context parameters injected by type (the session's Context&, Context const& or std::shared_ptr<Context>), then (boost::beast::http::request_header<> const&, matcher::context&), and returns taar::interceptor_result, directly or as an awaitable. It must not be a generic lambda.

Interceptors run shielded from cancellation like plain handlers; a shutdown requested meanwhile makes the request's answer close the connection.

session.add_interceptor([](http::request_header<> const& req, taar::matcher::context& ctx)
{
    auto const auth = req[http::field::authorization];
    if (!auth.starts_with("Bearer "))
        return taar::reject(http::status::unauthorized);
    ctx.attributes.set(principal {std::string {auth.substr(7)}});
    return taar::proceed();
});

The registered callable does not refer to the session, which stays movable.

template<typename MatcherType, typename Interceptor> 
  void add_interceptor(MatcherType && matcher, Interceptor interceptor);

Same as the one-argument overload, but the interceptor runs only when the matcher accepts the request header. The matcher is evaluated the way routes are; path arguments a target template extracts go into a scratch context that is discarded, and the interceptor receives the request's own context. Typical uses:

// Let CORS preflights through unauthenticated.
session.add_interceptor(!(method == http::verb::options), require_token);
// Keep the health check public.
session.add_interceptor(!(target == "/health"), require_token);

template<unspecified HandlerType> 
  void set_soft_error_handler(HandlerType handler);

The handler is invoked as handler(taar::failure const&) when a registered request handler throws. The session wraps the escaped exception with boost::taar::failure::from_exception once: a boost::taar::exception yields its own failure, a user's exception is kept and can be recognised with boost::taar::failure::as. The handler returns anything boost::taar::response_from accepts, synchronously or as an awaitable; the response is written to the client and determines whether the session continues (keep_alive() == true) or closes. A handler that throws escalates to the hard error handler.

session.set_soft_error_handler([](taar::failure const& f)
{
    if (auto const e = f.as<not_found>())
        return taar::response_builder(e->what()).set_status(http::status::not_found);
    return taar::response_builder(f.text()).set_status(taar::http_status_for(f));
});

The default handler answers failures that boost::taar::http_status_for maps to a 4xx status with that status and f.text() as a text/plain body, and escalates every other failure (user exceptions, internal codes) to the hard error handler.

template<unspecified HandlerType> 
  void set_hard_error_handler(HandlerType handler);

Invoked as handler(taar::failure const&) when the session aborts because of a connection-level failure (a transport error, a header that is too large, an I/O exception), when a streamed response fails after its header was sent, or when the soft error handler escalates (the default does so for user exceptions; the hard handler then sees the same failure). Transport errors carry their error_code; exceptions are wrapped by boost::taar::failure::from_exception. The handler is expected to log or otherwise report the failure (f.chain() renders it with category tags); the connection is already being torn down by the time the handler runs.

The default handler silently discards the exception, which is almost never the right choice in production; install at least a logging hook.