Router Class Reference

The central router for handling HTTP requests and middleware. More...

#include <Router.h>

Collaboration diagram for Router:

Public Member Functions
	Router ()
	Construct the router instance.
	Router (const Router &)=delete
Router &	operator= (const Router &)=delete
void	use (Middleware middleware)
	Register a global middleware function.
void	addRoute (const std::string &method, const std::string &path, RouteHandler handler, std::vector< Middleware > middleware={})
	Register a route with optional middleware.
void	addCatchAllGetRoute (RouteHandler handler, std::vector< Middleware > middleware={})
	Register a catch-all route with optional middleware.
void	addRoute (Router &router, const std::string &method, const std::string &path, std::function< void(HttpRequest &, HttpResponse &)> simpleHandler)
bool	handleRequest (HttpRequest &req, HttpResponse &res)
	Handle an incoming HTTP request.
bool	extractAuthorizationToken (const std::string &auth_header)
	Built-in route handler for /auth token testing.
std::string	getAuthorizationToken (const HttpRequest &req)
	Returns the cached Authorization token, or extracts it from the request.
bool	isAuthorizedForRoute (const Route &route, HttpRequest &req, HttpResponse &res)
	Check if a route requires and is granted JWT authorization.
void	printRoutes ()
	Print all registered routes to stdout.
HttpFileserver &	getFileHandler ()
	Get the file server instance.
void	serveStatic (HttpRequest &req, HttpResponse &res, const RouteMatch &match)
	Serve static files from the internal HttpFileserver.
void	listDirectory (HttpRequest &req, HttpResponse &res, const RouteMatch &match)
	Convenience method to list directory from the internal HttpFileserver.

Private Member Functions
void	withRoutes (const std::function< void(std::unordered_map< std::string, std::vector< Route > > &)> &fn)

Private Attributes
HttpFileserver	fileServer
	Internal file server instance.
std::unordered_map< std::string, std::vector< Route > >	routes
Route	catchallGetRoute
	Catch-all route for unmatched requests.
bool	hasCatchallGetRoute = false
	Flag to indicate if a catch-all route exists.
std::string	cached_token
	Cached Bearer token.
std::vector< Middleware >	globalMiddleware
SemaphoreHandle_t	lock_ = xSemaphoreCreateRecursiveMutexStatic(&lockBuffer_)

Static Private Attributes
static StaticSemaphore_t	lockBuffer_

Detailed Description

Supports:

• Dynamic route registration
• Regex-based matching
• Global and per-route middleware
• Optional JWT authentication

Definition at line 59 of file Router.h.

Constructor & Destructor Documentation

Router() [1/2]

Router::Router

(

)

Construct the router instance.

Definition at line 61 of file Router.cpp.

{
    lock_ = xSemaphoreCreateRecursiveMutex();
    configASSERT(lock_);
}

References configASSERT, and lock_.

Router() [2/2]

Router::Router ( const Router &  )

delete

Member Function Documentation

addCatchAllGetRoute()

void Router::addCatchAllGetRoute	(	RouteHandler	handler,
		std::vector< Middleware >	middleware = {}
	)

Parameters

method	HTTP method
path	URL path (can include {params})
handler	Handler to invoke on match
middleware	Optional list of middleware specific to this route

Definition at line 203 of file Router.cpp.

{
    TRACE("Adding catch-all GET route\n");
 
    RouteHandler finalHandler = [handler, this, middleware](HttpRequest &req, HttpResponse &res, const RouteMatch &match) {
        for (const auto &mw : globalMiddleware)
            if (!mw(req, res, match)) return;
        for (const auto &mw : middleware)
            if (!mw(req, res, match)) return;
        handler(req, res, match);
    };
 
    withRoutes([&](auto &) {
        catchallGetRoute = Route(
            "GET",
            "/(.*)",
            finalHandler,
            true,                          // authRequired
            !middleware.empty(),           // hasMiddleware
            {}                             // vector<string>
        );
        hasCatchallGetRoute = true;
    });
}

References catchallGetRoute, globalMiddleware, hasCatchallGetRoute, TRACE, and withRoutes().

Referenced by DashboardController::initRoutes().

Here is the call graph for this function:

Here is the caller graph for this function:

addRoute() [1/2]

void Router::addRoute	(	const std::string &	method,
		const std::string &	path,
		RouteHandler	handler,
		std::vector< Middleware >	middleware = {}
	)

Check if a route requires and is granted JWT authorization.

Parameters

method	HTTP method
path	URL path (can include {params})
handler	Handler to invoke on match
middleware	Optional list of middleware specific to this route
route	The matched route
req	HTTP request
res	HTTP response

Returns

true if access is granted

Register a route with optional middleware.

Check if a route requires and is granted JWT authorization.

Parameters

method	HTTP method
path	URL path (can include {params})
handler	Handler to invoke on match
middleware	Optional list of middleware specific to this route
route	The matched route
req	HTTP request
res	HTTP response

Returns

true if access is granted

Definition at line 144 of file Router.cpp.

{
    TRACE("Adding route: %s %s\n", method.c_str(), path.c_str());
 
    std::string regex_pattern = "^" + path;
    bool is_dynamic = false;
    std::vector<std::string> paramNames;
    size_t pos = 0;
 
    while ((pos = regex_pattern.find("{", pos)) != std::string::npos)
    {
        size_t end = regex_pattern.find("}", pos);
        if (end != std::string::npos)
        {
            std::string paramName = regex_pattern.substr(pos + 1, end - pos - 1);
            paramNames.push_back(paramName);
            regex_pattern.replace(pos, end - pos + 1, "([^/]+)");
            is_dynamic = true;
            pos += std::string("([^/]+)").size();
        }
        else
        {
            break;
        }
    }
 
    if (regex_pattern == "/.*")
    {
        regex_pattern = "^/(.*)$";
        is_dynamic = true;
    }
    regex_pattern += "$";
 
    RouteHandler finalHandler = [handler, paramNames, this, middleware](HttpRequest &req, HttpResponse &res, const RouteMatch &match)
    {
        for (const auto &mw : this->globalMiddleware)
        {
            if (!mw(req, res, match))
                return;
        }
 
        for (const auto &mw : middleware)
        {
            if (!mw(req, res, match))
                return;
        }
 
        handler(req, res, match);
    };
 
    withRoutes([&](auto &r)
    { 
        r[method].emplace_back(method, regex_pattern, finalHandler, is_dynamic, !middleware.empty(), paramNames);
    });
}

References globalMiddleware, TRACE, and withRoutes().

Referenced by addRoute(), App::initRoutes(), DashboardController::initRoutes(), and GpioController::initRoutes().

Here is the call graph for this function:

Here is the caller graph for this function:

addRoute() [2/2]

void Router::addRoute ( Router &  router, const std::string &  method, const std::string &  path, std::function< void(HttpRequest &, HttpResponse &)>  simpleHandler  )

inline

Definition at line 97 of file Router.h.

                                                                          {
            router.addRoute(method, path,
            [=](HttpRequest& req, HttpResponse& res, const RouteMatch&) {
            simpleHandler(req, res);
        });
    }              

References addRoute().

Here is the call graph for this function:

extractAuthorizationToken()

bool Router::extractAuthorizationToken

(

const std::string &

auth_header

)

Parameters

req	Incoming request
res	HttpResponse to send
params	Unused in this handler

Returns

true on success

Extracts and caches a Bearer token from an Authorization header.

Parameters

auth_header

Raw header string

Returns

true if token is valid

getAuthorizationToken()

std::string Router::getAuthorizationToken

(

const HttpRequest &

req

)

Returns the cached Authorization token, or extracts it from the request.

Parameters

req	The incoming request

Returns

Extracted Bearer token or empty string

Parameters

req	The incoming request

Returns

Extracted Bearer token or empty string

Definition at line 69 of file Router.cpp.

{
    std::string auth_header = req.getHeader("Authorization");
    std::string token = extractBearerToken(auth_header);
    if (token.empty())
    {
        TRACE("Error: Missing or invalid Authorization header format\n");
    }
    return token;
}

References extractBearerToken(), HttpRequest::getHeader(), and TRACE.

Here is the call graph for this function:

getFileHandler()

HttpFileserver & Router::getFileHandler ( )

inline

Returns

A reference to the internal HttpFileserver

Definition at line 162 of file Router.h.

{ return fileServer; }

References fileServer.

handleRequest()

bool Router::handleRequest	(	HttpRequest &	req,
		HttpResponse &	res
	)

Parameters

req	Fully parsed HttpRequest object
res	HttpResponse to send

Returns

true if the request was handled

false if no matching route was found

Definition at line 228 of file Router.cpp.

{
    TRACE("Router::handleRequest: %s %s\n", req.getMethod().c_str(), req.getPath().c_str());
    bool matched = false;
    const Route *matchedRoute = nullptr;
    std::vector<std::string> params;
 
    withRoutes([&](auto &r)
               {
                   auto it = r.find(req.getMethod());
                   if (it == r.end())
                       return;
 
                   for (const auto &route : it->second)
                   {
                       TRACE("Checking route: %s\n", route.path.c_str());
 
                       std::smatch match;
                       const std::string &path = req.getPath();
                       if (std::regex_match(path, match, route.compiledRegex)) // <--- USE precompiled
                       {
                           for (size_t i = 1; i < match.size(); ++i)
                           {
                               TRACE("Matched param %zu: %s\n", i, match[i].str().c_str());
                               params.push_back(urlDecode(match[i].str()));
                           }
                           matchedRoute = &route;
                           matched = true;
                           TRACE("Matched route: %s\n", route.path.c_str());
                           return;
                       }
                   }
               });
    TRACE("Matched: %s\n", matched ? "true" : "false");
    if (matched && matchedRoute)
    {
        RouteMatch match;
        match.ordered = params;
        const auto &names = matchedRoute->paramNames;
 
        for (size_t i = 0; i < names.size() && i < params.size(); ++i)
        {
            match.named[names[i]] = params[i];
        }
 
        TRACE("Matched route: %s\n", matchedRoute->path.c_str());
        matchedRoute->handler(req, res, match);
        return true;
    }
 
    TRACE("No matching regular route found\n");
 
    if (req.getMethod() == "GET" && hasCatchallGetRoute)
    {
        TRACE("Falling back to catch-all GET route\n");
        RouteMatch dummyMatch; // Dummy match for catch-all route
        catchallGetRoute.handler(req, res, dummyMatch);
        return true;
    }
    
    printRoutes();
    return false;
}

References catchallGetRoute, Route::compiledRegex, HttpRequest::getMethod(), HttpRequest::getPath(), Route::handler, hasCatchallGetRoute, RouteMatch::named, RouteMatch::ordered, Route::paramNames, Route::path, printRoutes(), TRACE, urlDecode(), and withRoutes().

Referenced by HttpServer::handleClient().

Here is the call graph for this function:

Here is the caller graph for this function:

isAuthorizedForRoute()

bool Router::isAuthorizedForRoute ( const Route &  route, HttpRequest &  req, HttpResponse &  res  )

inline

Parameters

route	The matched route
req	HTTP request
res	HTTP response

Returns

true if access is granted

Definition at line 151 of file Router.h.

{ return true; }

listDirectory()

void Router::listDirectory	(	HttpRequest &	req,
		HttpResponse &	res,
		const RouteMatch &	match
	)

Convenience method to list directory from the internal HttpFileserver.

Definition at line 321 of file Router.cpp.

{
 
    fileServer.handle_list_directory(req, res, match);
    ;
}

References fileServer, and HttpFileserver::handle_list_directory().

Referenced by DashboardController::initRoutes().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=()

Router & Router::operator= ( const Router &  )

delete

printRoutes()

void Router::printRoutes

(

)

Definition at line 294 of file Router.cpp.

{
    TRACE("Routes:\n");
    withRoutes([&](auto &r)
               {
        for (const auto &method_pair : routes)
        {
            TRACE("Method: %s\n", method_pair.first.c_str());
            for (const auto &route : method_pair.second)
            {
                TRACE("  Route: %s, Dynamic: %s, Requires Auth: %s\n",
                    route.path.c_str(),
                    route.isDynamic ? "true" : "false",
                    route.requiresAuth ? "true" : "false");
            }
        } });
}

References Route::isDynamic, Route::path, Route::requiresAuth, routes, TRACE, and withRoutes().

Referenced by handleRequest().

Here is the call graph for this function:

Here is the caller graph for this function:

serveStatic()

void Router::serveStatic	(	HttpRequest &	req,
		HttpResponse &	res,
		const RouteMatch &	match
	)

Serve static files from the internal HttpFileserver.

Definition at line 314 of file Router.cpp.

{
    fileServer.handle_static_request(req, res, match);
}

References fileServer, and HttpFileserver::handle_static_request().

Referenced by DashboardController::initRoutes().

Here is the call graph for this function:

Here is the caller graph for this function:

use()

void Router::use

(

Middleware

middleware

)

Parameters

middleware

Middleware to apply to all routes.

Register a global middleware function.

Parameters

middleware

Middleware to apply to all routes.

Definition at line 110 of file Router.cpp.

{
    globalMiddleware.push_back(middleware);
}

References globalMiddleware.

withRoutes()

void Router::withRoutes ( const std::function< void(std::unordered_map< std::string, std::vector< Route > > &)> &  fn )

private

Definition at line 328 of file Router.cpp.

{
    const char* taskName = pcTaskGetName(nullptr);
 
    if (xSemaphoreTakeRecursive(lock_, pdMS_TO_TICKS(5000)) != pdTRUE)
    {
        printf("[Router] [%s] ERROR - failed to acquire lock within timeout\n", taskName);
        return;
    }
 
    fn(routes);  
 
    xSemaphoreGiveRecursive(lock_);
    vTaskDelay(pdMS_TO_TICKS(1));  // Give any pending route-registration task a chance to run
}

References lock_, and routes.

Referenced by addCatchAllGetRoute(), addRoute(), handleRequest(), and printRoutes().

Here is the caller graph for this function:

Member Data Documentation

cached_token

std::string Router::cached_token

private

Definition at line 179 of file Router.h.

catchallGetRoute

Route Router::catchallGetRoute

private

Definition at line 177 of file Router.h.

Referenced by addCatchAllGetRoute(), and handleRequest().

fileServer

HttpFileserver Router::fileServer

private

Definition at line 175 of file Router.h.

Referenced by getFileHandler(), listDirectory(), and serveStatic().

globalMiddleware

std::vector<Middleware> Router::globalMiddleware

private

Definition at line 180 of file Router.h.

Referenced by addCatchAllGetRoute(), addRoute(), and use().

hasCatchallGetRoute

bool Router::hasCatchallGetRoute = false

private

Definition at line 178 of file Router.h.

Referenced by addCatchAllGetRoute(), and handleRequest().

lock_

SemaphoreHandle_t Router::lock_ = xSemaphoreCreateRecursiveMutexStatic(&lockBuffer_)

private

Definition at line 183 of file Router.h.

Referenced by Router(), and withRoutes().

lockBuffer_

StaticSemaphore_t Router::lockBuffer_

staticprivate

Definition at line 182 of file Router.h.

routes

std::unordered_map<std::string, std::vector<Route> > Router::routes

private

Definition at line 176 of file Router.h.

Referenced by printRoutes(), and withRoutes().

---

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

• Router.h
• Router.cpp