Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/http

// Official repository: https://github.com/cppalliance/http

//

//

#ifndef BOOST_HTTP_SERVER_ROUTE_HANDLER_HPP

#ifndef BOOST_HTTP_SERVER_ROUTE_HANDLER_HPP

#define BOOST_HTTP_SERVER_ROUTE_HANDLER_HPP

#define BOOST_HTTP_SERVER_ROUTE_HANDLER_HPP

#include <boost/http/detail/config.hpp>

#include <boost/http/detail/config.hpp>

#include <boost/http/method.hpp>

#include <boost/http/method.hpp>

#include <boost/http/detail/except.hpp>

#include <boost/http/detail/except.hpp>

#include <boost/http/datastore.hpp>

#include <boost/http/datastore.hpp>

#include <boost/http/request.hpp>

#include <boost/http/request.hpp>

#include <boost/http/response.hpp>

#include <boost/http/response.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/core/detail/string_view.hpp>

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers.hpp>

#include <boost/capy/buffers/make_buffer.hpp>

#include <boost/capy/buffers/make_buffer.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_task.hpp>

#include <boost/capy/io_task.hpp>

#include <boost/capy/task.hpp>

#include <boost/capy/task.hpp>

#include <boost/capy/write.hpp>

#include <boost/capy/write.hpp>

#include <boost/capy/io/any_buffer_source.hpp>

#include <boost/capy/io/any_buffer_source.hpp>

#include <boost/capy/io/any_buffer_sink.hpp>

#include <boost/capy/io/any_buffer_sink.hpp>

#include <boost/url/url_view.hpp>

#include <boost/url/url_view.hpp>

#include <boost/system/error_category.hpp>

#include <boost/system/error_category.hpp>

#include <boost/system/error_code.hpp>

#include <boost/system/error_code.hpp>

#include <concepts>

#include <concepts>

#include <exception>

#include <exception>

#include <memory>

#include <memory>

#include <span>

#include <span>

#include <string>

#include <string>

#include <type_traits>

#include <type_traits>

#include <utility>

#include <utility>

#include <vector>

#include <vector>

namespace boost {

namespace boost {

namespace http {

namespace http {

/** Directive values for route handler results.

/** Directive values for route handler results.

    These values indicate how the router should proceed

    These values indicate how the router should proceed

    after a handler completes. Handlers return one of

    after a handler completes. Handlers return one of

    the predefined constants (@ref route_done, @ref route_next,

    the predefined constants (@ref route_done, @ref route_next,

    @ref route_next_route, @ref route_close) or an error code.

    @ref route_next_route, @ref route_close) or an error code.

    @see route_result, route_task

    @see route_result, route_task

*/

*/

enum class route_what

enum class route_what

{

{

    /// Handler completed successfully, response was sent

    /// Handler completed successfully, response was sent

    done,

    done,

    /// Handler declined, try next handler in the route

    /// Handler declined, try next handler in the route

    next,

    next,

    /// Handler declined, skip to next matching route

    /// Handler declined, skip to next matching route

    next_route,

    next_route,

    /// Handler requests connection closure

    /// Handler requests connection closure

    close,

    close,

    /// Handler encountered an error

    /// Handler encountered an error

    error

    error

};

};

//------------------------------------------------

//------------------------------------------------

/** The result type returned by route handlers.

/** The result type returned by route handlers.

    This class represents the outcome of a route handler.

    This class represents the outcome of a route handler.

    Handlers return this type to indicate how the router

    Handlers return this type to indicate how the router

    should proceed. Construct from a directive constant

    should proceed. Construct from a directive constant

    or an error code:

    or an error code:

    @code

    @code

    route_task my_handler(route_params& p)

    route_task my_handler(route_params& p)

    {

    {

        if(! authorized(p))

        if(! authorized(p))

            co_return route_next;        // try next handler

            co_return route_next;        // try next handler

        if(auto ec = process(p); ec)

        if(auto ec = process(p); ec)

            co_return ec;                // return error

            co_return ec;                // return error

        co_return route_done;            // success

        co_return route_done;            // success

    }

    }

    @endcode

    @endcode

    @par Checking Results

    @par Checking Results

    Use @ref what() to determine the directive, and

    Use @ref what() to determine the directive, and

    @ref error() to retrieve any error code:

    @ref error() to retrieve any error code:

    @code

    @code

    route_result rv = co_await handler(p);

    route_result rv = co_await handler(p);

    if(rv.what() == route_what::error)

    if(rv.what() == route_what::error)

        handle_error(rv.error());

        handle_error(rv.error());

    @endcode

    @endcode

    @see route_task, route_what, route_done, route_next

    @see route_task, route_what, route_done, route_next

*/

*/

class BOOST_HTTP_DECL

class BOOST_HTTP_DECL

    route_result

    route_result

{

{

    system::error_code ec_;

    system::error_code ec_;

    template<route_what T>

    template<route_what T>

    struct what_t {};

    struct what_t {};

    route_result(system::error_code ec);

    route_result(system::error_code ec);

    void set(route_what w);

    void set(route_what w);

public:

public:

    /** Construct from a directive constant.

    /** Construct from a directive constant.

        This constructor allows implicit conversion from

        This constructor allows implicit conversion from

        the predefined constants (@ref route_done, @ref route_next,

        the predefined constants (@ref route_done, @ref route_next,

        @ref route_next_route, @ref route_close).

        @ref route_next_route, @ref route_close).

        @code

        @code

        route_task handler(route_params& p)

        route_task handler(route_params& p)

        {

        {

            co_return route_done;  // implicitly converts

            co_return route_done;  // implicitly converts

        }

        }

        @endcode

        @endcode

    */

    */

    template<route_what W>

    template<route_what W>

        static_assert(W != route_what::error);

        static_assert(W != route_what::error);

    /** Return the directive for this result.

    /** Return the directive for this result.

        Call this to determine how the router should proceed:

        Call this to determine how the router should proceed:

        @code

        @code

        route_result rv = co_await handler(p);

        route_result rv = co_await handler(p);

        switch(rv.what())

        switch(rv.what())

        {

        {

        case route_what::done:

        case route_what::done:

            // response sent, done with request

            // response sent, done with request

            break;

            break;

        case route_what::next:

        case route_what::next:

            // try next handler

            // try next handler

            break;

            break;

        case route_what::error:

        case route_what::error:

            log_error(rv.error());

            log_error(rv.error());

            break;

            break;

        }

        }

        @endcode

        @endcode

        @return The directive value.

        @return The directive value.

    */

    */

    auto

    auto

    what() const noexcept ->

    what() const noexcept ->

        route_what;

        route_what;

    /** Return the error code, if any.

    /** Return the error code, if any.

        If @ref what() returns `route_what::error`, this

        If @ref what() returns `route_what::error`, this

        returns the underlying error code. Otherwise returns

        returns the underlying error code. Otherwise returns

        a default-constructed (non-failing) error code.

        a default-constructed (non-failing) error code.

        @return The error code, or a non-failing code.

        @return The error code, or a non-failing code.

    */

    */

    auto

    auto

    error() const noexcept ->

    error() const noexcept ->

        system::error_code;

        system::error_code;

    /** Return true if the result indicates an error.

    /** Return true if the result indicates an error.

        @return `true` if @ref what() equals `route_what::error`.

        @return `true` if @ref what() equals `route_what::error`.

    */

    */

    {

    {

    }

    }

    static constexpr route_result::what_t<route_what::done> route_done{};

    static constexpr route_result::what_t<route_what::done> route_done{};

    static constexpr route_result::what_t<route_what::next> route_next{};

    static constexpr route_result::what_t<route_what::next> route_next{};

    static constexpr route_result::what_t<route_what::next_route> route_next_route{};

    static constexpr route_result::what_t<route_what::next_route> route_next_route{};

    static constexpr route_result::what_t<route_what::close> route_close{};

    static constexpr route_result::what_t<route_what::close> route_close{};

    friend route_result route_error(system::error_code ec) noexcept;

    friend route_result route_error(system::error_code ec) noexcept;

    template<class E>

    template<class E>

    friend auto route_error(E e) noexcept ->

    friend auto route_error(E e) noexcept ->

        std::enable_if_t<

        std::enable_if_t<

            system::is_error_code_enum<E>::value,

            system::is_error_code_enum<E>::value,

            route_result>;

            route_result>;

};

};

//------------------------------------------------

//------------------------------------------------

/** Handler completed successfully.

/** Handler completed successfully.

    Return this from a handler to indicate the response

    Return this from a handler to indicate the response

    was sent and the request is complete:

    was sent and the request is complete:

    @code

    @code

    route_task handler(route_params& p)

    route_task handler(route_params& p)

    {

    {

        p.res.set(field::content_type, "text/plain");

        p.res.set(field::content_type, "text/plain");

        co_await p.send("Hello, World!");

        co_await p.send("Hello, World!");

        co_return route_done;

        co_return route_done;

    }

    }

    @endcode

    @endcode

*/

*/

inline constexpr decltype(auto) route_done = route_result::route_done;

inline constexpr decltype(auto) route_done = route_result::route_done;

/** Handler declined, try next handler.

/** Handler declined, try next handler.

    Return this from a handler to decline processing

    Return this from a handler to decline processing

    and allow the next handler in the route to try:

    and allow the next handler in the route to try:

    @code

    @code

    route_task auth_handler(route_params& p)

    route_task auth_handler(route_params& p)

    {

    {

        if(! p.req.exists(field::authorization))

        if(! p.req.exists(field::authorization))

            co_return route_next;  // let another handler try

            co_return route_next;  // let another handler try

        // process authenticated request...

        // process authenticated request...

        co_return route_done;

        co_return route_done;

    }

    }

    @endcode

    @endcode

*/

*/

inline constexpr decltype(auto) route_next = route_result::route_next;

inline constexpr decltype(auto) route_next = route_result::route_next;

/** Handler declined, skip to next route.

/** Handler declined, skip to next route.

    Return this from a handler to skip all remaining

    Return this from a handler to skip all remaining

    handlers in the current route and proceed to the

    handlers in the current route and proceed to the

    next matching route:

    next matching route:

    @code

    @code

    route_task version_check(route_params& p)

    route_task version_check(route_params& p)

    {

    {

        if(p.req.version() < 11)

        if(p.req.version() < 11)

            co_return route_next_route;  // skip this route

            co_return route_next_route;  // skip this route

        co_return route_next;  // continue with this route

        co_return route_next;  // continue with this route

    }

    }

    @endcode

    @endcode

*/

*/

inline constexpr decltype(auto) route_next_route = route_result::route_next_route;

inline constexpr decltype(auto) route_next_route = route_result::route_next_route;

/** Handler requests connection closure.

/** Handler requests connection closure.

    Return this from a handler to immediately close

    Return this from a handler to immediately close

    the connection without sending a response:

    the connection without sending a response:

    @code

    @code

    route_task ban_check(route_params& p)

    route_task ban_check(route_params& p)

    {

    {

        if(is_banned(p.req.remote_address()))

        if(is_banned(p.req.remote_address()))

            co_return route_close;  // drop connection

            co_return route_close;  // drop connection

        co_return route_next;

        co_return route_next;

    }

    }

    @endcode

    @endcode

*/

*/

inline constexpr decltype(auto) route_close = route_result::route_close;

inline constexpr decltype(auto) route_close = route_result::route_close;

/** Construct from an error code.

/** Construct from an error code.

    Use this constructor to return an error from a handler.

    Use this constructor to return an error from a handler.

    The error code must represent a failure condition.

    The error code must represent a failure condition.

    @param ec The error code to return.

    @param ec The error code to return.

    @throw std::invalid_argument if `!ec` (non-failing code).

    @throw std::invalid_argument if `!ec` (non-failing code).

*/

*/

{

{

}

}

/** Construct from an error enum.

/** Construct from an error enum.

    Use this overload to return an error from a handler

    Use this overload to return an error from a handler

    using any type satisfying `is_error_code_enum`.

    using any type satisfying `is_error_code_enum`.

    @param e The error enum value to return.

    @param e The error enum value to return.

*/

*/

template<class E>

template<class E>

    std::enable_if_t<

    std::enable_if_t<

        system::is_error_code_enum<E>::value,

        system::is_error_code_enum<E>::value,

        route_result>

        route_result>

{

{

}

}

//------------------------------------------------

//------------------------------------------------

/** Convenience alias for route handler return type.

/** Convenience alias for route handler return type.

    Route handlers are coroutines that return a @ref route_result

    Route handlers are coroutines that return a @ref route_result

    indicating how the router should proceed. This alias simplifies

    indicating how the router should proceed. This alias simplifies

    handler declarations:

    handler declarations:

    @code

    @code

    route_task my_handler(route_params& p)

    route_task my_handler(route_params& p)

    {

    {

        // process request...

        // process request...

        co_return route_done;

        co_return route_done;

    }

    }

    route_task auth_middleware(route_params& p)

    route_task auth_middleware(route_params& p)

    {

    {

        if(! check_token(p))

        if(! check_token(p))

        {

        {

            p.res.set_status(status::unauthorized);

            p.res.set_status(status::unauthorized);

            co_await p.send();

            co_await p.send();

            co_return route_done;

            co_return route_done;

        }

        }

        co_return route_next;  // continue to next handler

        co_return route_next;  // continue to next handler

    }

    }

    @endcode

    @endcode

    @see route_result, route_params

    @see route_result, route_params

*/

*/

using route_task = capy::task<route_result>;

using route_task = capy::task<route_result>;

//------------------------------------------------

//------------------------------------------------

template<class, class> class router;

template<class, class> class router;

namespace detail {

namespace detail {

struct route_params_access;

struct route_params_access;

class router_base;

class router_base;

struct route_params_base_privates

struct route_params_base_privates

{

{

    std::string verb_str_;

    std::string verb_str_;

    std::string decoded_path_;

    std::string decoded_path_;

    system::error_code ec_;

    system::error_code ec_;

    std::exception_ptr ep_;

    std::exception_ptr ep_;

    std::size_t pos_ = 0;

    std::size_t pos_ = 0;

    std::size_t resume_ = 0;

    std::size_t resume_ = 0;

    http::method verb_ =

    http::method verb_ =

        http::method::unknown;

        http::method::unknown;

    bool addedSlash_ = false;

    bool addedSlash_ = false;

    bool case_sensitive = false;

    bool case_sensitive = false;

    bool strict = false;

    bool strict = false;

    char kind_ = 0;

    char kind_ = 0;

};

};

} // detail

} // detail

//------------------------------------------------

//------------------------------------------------

/** Parameters object for HTTP route handlers.

/** Parameters object for HTTP route handlers.

    This structure holds all the context needed for a route

    This structure holds all the context needed for a route

    handler to process an HTTP request and generate a response.

    handler to process an HTTP request and generate a response.

    @par Example

    @par Example

    @code

    @code

    route_task my_handler(route_params& p)

    route_task my_handler(route_params& p)

    {

    {

        p.res.set(field::content_type, "text/plain");

        p.res.set(field::content_type, "text/plain");

        co_await p.send("Hello, World!");

        co_await p.send("Hello, World!");

        co_return route_done;

        co_return route_done;

    }

    }

    @endcode

    @endcode

    @see route_task, route_result

    @see route_task, route_result

*/

*/

class BOOST_HTTP_SYMBOL_VISIBLE

class BOOST_HTTP_SYMBOL_VISIBLE

    route_params

    route_params

{

{

    detail::route_params_base_privates priv_;

    detail::route_params_base_privates priv_;

public:

public:

    struct match_result;

    struct match_result;

    /** Return true if the request method matches `m`

    /** Return true if the request method matches `m`

    */

    */

        http::method m) const noexcept

        http::method m) const noexcept

    {

    {

    }

    }

    /** Return true if the request method matches `s`

    /** Return true if the request method matches `s`

    */

    */

    BOOST_HTTP_DECL

    BOOST_HTTP_DECL

    bool is_method(

    bool is_method(

        core::string_view s) const noexcept;

        core::string_view s) const noexcept;

    /** The mount path of the current router

    /** The mount path of the current router

        This is the portion of the request path

        This is the portion of the request path

        which was matched to select the handler.

        which was matched to select the handler.

        The remaining portion is available in

        The remaining portion is available in

        @ref path.

        @ref path.

    */

    */

    core::string_view base_path;

    core::string_view base_path;

    /** The current pathname, relative to the base path

    /** The current pathname, relative to the base path

    */

    */

    core::string_view path;

    core::string_view path;

    /** Captured route parameters

    /** Captured route parameters

        Contains name-value pairs extracted from the path

        Contains name-value pairs extracted from the path

        by matching :param and *wildcard tokens.

        by matching :param and *wildcard tokens.

    */

    */

    std::vector<std::pair<std::string, std::string>> params;

    std::vector<std::pair<std::string, std::string>> params;

    /// The complete request target

    /// The complete request target

    urls::url_view url;

    urls::url_view url;

    /// The HTTP request

    /// The HTTP request

    http::request req;

    http::request req;

    /// The HTTP response

    /// The HTTP response

    http::response res;

    http::response res;

    /// Provides access to the request body

    /// Provides access to the request body

    capy::any_buffer_source req_body;

    capy::any_buffer_source req_body;

    /// Provides access to the response body

    /// Provides access to the response body

    capy::any_buffer_sink res_body;

    capy::any_buffer_sink res_body;

    /// Arbitrary per-route data

    /// Arbitrary per-route data

    http::datastore route_data;

    http::datastore route_data;

    /// Arbitrary per-session data

    /// Arbitrary per-session data

    http::datastore session_data;

    http::datastore session_data;

    BOOST_HTTP_DECL ~route_params();

    BOOST_HTTP_DECL ~route_params();

    BOOST_HTTP_DECL void reset();

    BOOST_HTTP_DECL void reset();

    BOOST_HTTP_DECL route_params& status(http::status code);

    BOOST_HTTP_DECL route_params& status(http::status code);

    /** Send the response with an optional body.

    /** Send the response with an optional body.

    */

    */

    BOOST_HTTP_DECL capy::io_task<> send(std::string_view body = {});

    BOOST_HTTP_DECL capy::io_task<> send(std::string_view body = {});

private:

private:

    template<class, class>

    template<class, class>

    friend class router;

    friend class router;

    friend class detail::router_base;

    friend class detail::router_base;

    friend struct detail::route_params_access;

    friend struct detail::route_params_access;

    route_params& operator=(

    route_params& operator=(

        route_params const&) = delete;

        route_params const&) = delete;

};

};

struct route_params::

struct route_params::

    match_result

    match_result

{

{

    std::vector<std::pair<std::string, std::string>> params_;

    std::vector<std::pair<std::string, std::string>> params_;

        route_params& p,

        route_params& p,

        std::size_t n)

        std::size_t n)

    {

    {

            p.base_path.data(),

            p.base_path.data(),

        {

        {

        }

        }

        else

        else

        {

        {

            // append a soft slash

            // append a soft slash

        }

        }

    }

    }

    void restore_path(

    void restore_path(

        route_params& p)

        route_params& p)

    {

    {

        if( n_ > 0 &&

        if( n_ > 0 &&

            p.priv_.addedSlash_ &&

            p.priv_.addedSlash_ &&

            p.path.data() ==

            p.path.data() ==

                p.priv_.decoded_path_.data() +

                p.priv_.decoded_path_.data() +

                p.priv_.decoded_path_.size() - 1)

                p.priv_.decoded_path_.size() - 1)

        {

        {

            // remove soft slash

            // remove soft slash

            p.path = {

            p.path = {

                p.base_path.data() +

                p.base_path.data() +

                p.base_path.size(), 0 };

                p.base_path.size(), 0 };

        }

        }

        p.base_path.remove_suffix(n_);

        p.base_path.remove_suffix(n_);

        p.path = {

        p.path = {

            p.path.data() - n_,

            p.path.data() - n_,

            p.path.size() + n_ };

            p.path.size() + n_ };

    }

    }

private:

private:

    std::size_t n_ = 0; // chars moved from path to base_path

    std::size_t n_ = 0; // chars moved from path to base_path

};

};

//------------------------------------------------

//------------------------------------------------

namespace detail {

namespace detail {

template<class H, class... Args>

template<class H, class... Args>

concept returns_route_task = std::same_as<

concept returns_route_task = std::same_as<

    std::invoke_result_t<H, Args...>, route_task>;

    std::invoke_result_t<H, Args...>, route_task>;

struct route_params_access

struct route_params_access

{

{

    route_params& rp;

    route_params& rp;

    {

    {

    }

    }

    {

    {

    }

    }

};

};

} // detail

} // detail