Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
Loading...
Searching...
No Matches
orbit::routing::Router Class Reference

Manages routing of HTTP requests to their appropriate handlers. More...

#include <Router.hpp>

Collaboration diagram for orbit::routing::Router:

Classes

class  RouteBuilder
 A builder class for fluent route configuration. More...
 
struct  StaticRoute
 

Public Member Functions

 Router (const std::string &prefix="", Router *parent=nullptr)
 Constructs a new Router.
 
openapi::OpenApiRegistry & openapi ()
 The OpenAPI registry for this router tree (shared by its groups).
 
RouteBuilder route (const std::string &path, http::HttpMethod method=http::HttpMethod::GET)
 Initiates a route builder for a specific path and method.
 
void group (const std::string &prefix, std::function< void(Router &)> callback)
 Creates a route group with a specific prefix.
 
void add_route (http::HttpMethod method, const std::string &path, RouteHandler handler)
 
void add_route (http::HttpMethod method, const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
void add_route_with_meta (http::HttpMethod method, const std::string &path, std::vector< Middleware > mws, const openapi::RouteMetadata &meta, RouteHandler handler)
 
Router & get (const std::string &path, RouteHandler handler)
 
Router & get (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
Router & post (const std::string &path, RouteHandler handler)
 
Router & post (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
Router & put (const std::string &path, RouteHandler handler)
 
Router & put (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
Router & patch (const std::string &path, RouteHandler handler)
 
Router & patch (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
Router & del (const std::string &path, RouteHandler handler)
 
Router & del (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
Router & options (const std::string &path, RouteHandler handler)
 
Router & options (const std::string &path, std::vector< Middleware > mws, RouteHandler handler)
 
void ws (const std::string &path, WsHandler handler)
 
void ws (const std::string &path, std::vector< Middleware > mws, WsHandler handler)
 
bool run_ws_middlewares (const std::string &path, http::HttpRequest &request, std::shared_ptr< http::ResponseWriter > response_writer) const
 Runs global, group and route middleware for a WebSocket upgrade.
 
void use (Middleware m)
 
void use (const std::string &prefix, Middleware m)
 Runs m only for requests under prefix: the prefix itself and anything below it ("/svc" and "/svc/..."; not "/svcx").
 
void not_found (RouteHandler handler)
 
void on_error (ErrorHandler handler)
 
void route (http::HttpRequest &request, std::shared_ptr< http::ResponseWriter > response_writer) const
 
bool has_ws_route (const std::string &path) const
 
std::vector< std::string > validate_routes () const
 Finds routes registered more than once: the same HTTP method and exact path pattern (text, not matching behaviour) added twice, which silently keeps only one of them (the last registration for a static path, the first match for a dynamic one) with no warning otherwise.
 
WsHandler get_ws_route (const std::string &path) const
 
bool is_stream_route (http::HttpMethod method, const std::string &path) const
 
void add_stream_route (http::HttpMethod method, const std::string &path, RouteHandler handler)
 

Private Member Functions

void handle_exception (std::exception_ptr error, http::HttpRequest &request, std::shared_ptr< http::ResponseWriter > response_writer, const ErrorScope *scope=nullptr) const
 
std::string make_route_key (http::HttpMethod method, std::string_view path) const
 
void mark_stream_route (http::HttpMethod method, const std::string &full_path)
 
std::vector< std::string > split_path (std::string_view path) const
 
Router * root ()
 
const Router * root () const
 

Static Private Member Functions

static int match_segments (const std::vector< std::string > &pattern, const std::vector< std::string > &request, std::unordered_map< std::string, std::string > *params)
 
static bool is_wildcard (const std::string &segment)
 

Private Attributes

std::string prefix_
 
Router * parent_ {nullptr}
 
std::shared_ptr< openapi::OpenApiRegistry > openapi_
 
std::vector< Middleware > local_middlewares_
 
ErrorHandler error_handler_
 
std::shared_ptr< ErrorScope > error_scope_
 
RouteHandler not_found_handler_
 
std::unordered_map< std::string, StaticRoute > routes_
 
std::unordered_map< std::string, WsRoute > ws_routes_
 
std::vector< DynamicRoute > dynamic_routes_
 
std::vector< Middleware > middlewares_
 
std::unordered_set< std::string > stream_routes_
 
std::vector< DynamicRoute > dynamic_stream_routes_
 
std::unordered_map< std::string, int > registration_counts_
 

Detailed Description

Manages routing of HTTP requests to their appropriate handlers.

Constructor & Destructor Documentation

◆ Router()

orbit::routing::Router::Router ( const std::string &  prefix = "",
Router *  parent = nullptr 
)
inline

Constructs a new Router.

Parameters
prefixThe route prefix for this router.
parentPointer to the parent router, if any.

Member Function Documentation

◆ add_route() [1/2]

void orbit::routing::Router::add_route ( http::HttpMethod  method,
const std::string &  path,
RouteHandler  handler 
)

◆ add_route() [2/2]

void orbit::routing::Router::add_route ( http::HttpMethod  method,
const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ add_route_with_meta()

void orbit::routing::Router::add_route_with_meta ( http::HttpMethod  method,
const std::string &  path,
std::vector< Middleware >  mws,
const openapi::RouteMetadata &  meta,
RouteHandler  handler 
)

◆ add_stream_route()

void orbit::routing::Router::add_stream_route ( http::HttpMethod  method,
const std::string &  path,
RouteHandler  handler 
)

◆ del() [1/2]

Router & orbit::routing::Router::del ( const std::string &  path,
RouteHandler  handler 
)

◆ del() [2/2]

Router & orbit::routing::Router::del ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ get() [1/2]

Router & orbit::routing::Router::get ( const std::string &  path,
RouteHandler  handler 
)

◆ get() [2/2]

Router & orbit::routing::Router::get ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ get_ws_route()

WsHandler orbit::routing::Router::get_ws_route ( const std::string &  path) const

◆ group()

void orbit::routing::Router::group ( const std::string &  prefix,
std::function< void(Router &)>  callback 
)

Creates a route group with a specific prefix.

Parameters
prefixThe URL prefix for the group.
callbackA function to configure routes within the group.

◆ handle_exception()

void orbit::routing::Router::handle_exception ( std::exception_ptr  error,
http::HttpRequest &  request,
std::shared_ptr< http::ResponseWriter >  response_writer,
const ErrorScope *  scope = nullptr 
) const
private

◆ has_ws_route()

bool orbit::routing::Router::has_ws_route ( const std::string &  path) const

◆ is_stream_route()

bool orbit::routing::Router::is_stream_route ( http::HttpMethod  method,
const std::string &  path 
) const

◆ is_wildcard()

static bool orbit::routing::Router::is_wildcard ( const std::string &  segment)
inlinestaticprivate

◆ make_route_key()

std::string orbit::routing::Router::make_route_key ( http::HttpMethod  method,
std::string_view  path 
) const
private

◆ mark_stream_route()

void orbit::routing::Router::mark_stream_route ( http::HttpMethod  method,
const std::string &  full_path 
)
private

◆ match_segments()

static int orbit::routing::Router::match_segments ( const std::vector< std::string > &  pattern,
const std::vector< std::string > &  request,
std::unordered_map< std::string, std::string > *  params 
)
staticprivate

◆ not_found()

void orbit::routing::Router::not_found ( RouteHandler  handler)

Answers requests that match no route (instead of "404 Not Found"). A path that exists under other methods still gets 405 with Allow.

◆ on_error()

void orbit::routing::Router::on_error ( ErrorHandler  handler)

Handles exceptions from routes. On the app (root router) it covers every route, unmatched requests and app-level middleware; in a group it covers that group's routes and nested groups, before or after they are registered.

◆ openapi()

openapi::OpenApiRegistry & orbit::routing::Router::openapi ( )
inline

The OpenAPI registry for this router tree (shared by its groups).

◆ options() [1/2]

Router & orbit::routing::Router::options ( const std::string &  path,
RouteHandler  handler 
)

◆ options() [2/2]

Router & orbit::routing::Router::options ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ patch() [1/2]

Router & orbit::routing::Router::patch ( const std::string &  path,
RouteHandler  handler 
)

◆ patch() [2/2]

Router & orbit::routing::Router::patch ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ post() [1/2]

Router & orbit::routing::Router::post ( const std::string &  path,
RouteHandler  handler 
)

◆ post() [2/2]

Router & orbit::routing::Router::post ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ put() [1/2]

Router & orbit::routing::Router::put ( const std::string &  path,
RouteHandler  handler 
)

◆ put() [2/2]

Router & orbit::routing::Router::put ( const std::string &  path,
std::vector< Middleware >  mws,
RouteHandler  handler 
)

◆ root() [1/2]

Router * orbit::routing::Router::root ( )
inlineprivate

◆ root() [2/2]

const Router * orbit::routing::Router::root ( ) const
inlineprivate

◆ route() [1/2]

RouteBuilder orbit::routing::Router::route ( const std::string &  path,
http::HttpMethod  method = http::HttpMethod::GET 
)
inline

Initiates a route builder for a specific path and method.

Parameters
pathThe URL path.
methodThe HTTP method (default is GET).
Returns
A RouteBuilder instance to configure the route.
router.route("/users", HttpMethod::POST)
.summary("Create a user")
.handler([](auto& req, auto res) { ... });

◆ route() [2/2]

void orbit::routing::Router::route ( http::HttpRequest &  request,
std::shared_ptr< http::ResponseWriter >  response_writer 
) const

◆ run_ws_middlewares()

bool orbit::routing::Router::run_ws_middlewares ( const std::string &  path,
http::HttpRequest &  request,
std::shared_ptr< http::ResponseWriter >  response_writer 
) const

Runs global, group and route middleware for a WebSocket upgrade.

Returns
True if every middleware let the request through; false if one stopped it (it has then already sent a response).

◆ split_path()

std::vector< std::string > orbit::routing::Router::split_path ( std::string_view  path) const
private

◆ use() [1/2]

void orbit::routing::Router::use ( const std::string &  prefix,
Middleware  m 
)

Runs m only for requests under prefix: the prefix itself and anything below it ("/svc" and "/svc/..."; not "/svcx").

Runs before route matching, so it can serve paths that have no route, e.g. app.use("/api", orbit::middleware::proxy(opts)).

Exceptions
std::invalid_argumentif prefix does not start with '/'.

◆ use() [2/2]

void orbit::routing::Router::use ( Middleware  m)

◆ validate_routes()

std::vector< std::string > orbit::routing::Router::validate_routes ( ) const

Finds routes registered more than once: the same HTTP method and exact path pattern (text, not matching behaviour) added twice, which silently keeps only one of them (the last registration for a static path, the first match for a dynamic one) with no warning otherwise.

Returns
One line per duplicated method+pattern ("GET /tasks/{id} registered 2 times"), empty if there are none. Call this yourself to check without starting a server; App::listen() calls it and refuses to start if it is non-empty.

◆ ws() [1/2]

void orbit::routing::Router::ws ( const std::string &  path,
std::vector< Middleware >  mws,
WsHandler  handler 
)

◆ ws() [2/2]

void orbit::routing::Router::ws ( const std::string &  path,
WsHandler  handler 
)

Member Data Documentation

◆ dynamic_routes_

std::vector<DynamicRoute> orbit::routing::Router::dynamic_routes_
private

◆ dynamic_stream_routes_

std::vector<DynamicRoute> orbit::routing::Router::dynamic_stream_routes_
private

◆ error_handler_

ErrorHandler orbit::routing::Router::error_handler_
private

◆ error_scope_

std::shared_ptr<ErrorScope> orbit::routing::Router::error_scope_
private

◆ local_middlewares_

std::vector<Middleware> orbit::routing::Router::local_middlewares_
private

◆ middlewares_

std::vector<Middleware> orbit::routing::Router::middlewares_
private

◆ not_found_handler_

RouteHandler orbit::routing::Router::not_found_handler_
private

◆ openapi_

std::shared_ptr<openapi::OpenApiRegistry> orbit::routing::Router::openapi_
private

◆ parent_

Router* orbit::routing::Router::parent_ {nullptr}
private

◆ prefix_

std::string orbit::routing::Router::prefix_
private

◆ registration_counts_

std::unordered_map<std::string, int> orbit::routing::Router::registration_counts_
private

◆ routes_

std::unordered_map<std::string, StaticRoute> orbit::routing::Router::routes_
private

◆ stream_routes_

std::unordered_set<std::string> orbit::routing::Router::stream_routes_
private

◆ ws_routes_

std::unordered_map<std::string, WsRoute> orbit::routing::Router::ws_routes_
private

The documentation for this class was generated from the following file: