Mirror
/
Crow
mirror of https://github.com/CrowCpp/Crow.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added documentation of "crow::App", "crow::SimpleApp", "crow" 

(namespace), all macros defined in "crow/app.h".
This commit is contained in:
Nabzokek 2024-04-20 21:40:11 -04:00
parent 3e9eb1172a
commit 3228244ceb
5 changed files with 219 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Doxyfile
View File

@ -499,7 +499,7 @@ NUM_PROC_THREADS = 1
# normally produced when WARNINGS is set to YES.
# The default value is: NO.
EXTRACT_ALL = NO
EXTRACT_ALL = YES # DEBUG
# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
# be included in the documentation.
@ -772,7 +772,7 @@ SHOW_FILES = YES
# Folder Tree View (if specified).
# The default value is: YES.
SHOW_NAMESPACES = NO
SHOW_NAMESPACES = YES
# The FILE_VERSION_FILTER tag can be used to specify a program or script that
# doxygen should invoke to get the current version for each file (typically from

267
include/crow/app.h
View File

@ -24,50 +24,181 @@
#include "crow/compression.h"
#endif
#ifdef CROW_MSVC_WORKAROUND
#define CROW_ROUTE(app, url) app.route_dynamic(url)
#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url)
#else
#define CROW_ROUTE(app, url) app.route_dynamic(url) // See the documentation in the comment bellow.
#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_dynamic(url) // See the documentation in the comment bellow.
#else // #ifdef CROW_MSVC_WORKAROUND
/**
* \def CROW_ROUTE(app, url)
* \brief Creates a route for app using a rule.
*
* It use crow::Crow::route_dynamic or crow::Crow::route to define
* a rule for your application. It's usage is like this:
*
* ```cpp
* auto app = crow::SimpleApp(); // or crow::App()
* CROW_ROUTE(app, "/")
* ([](){
* return "<h1>Hello, world!</h1>";
* });
* ```
*
* This is the recommended way to define routes in a crow application.
* \see [Page of guide "Routes"](https://crowcpp.org/master/guides/routes/).
*/
#define CROW_ROUTE(app, url) app.template route<crow::black_magic::get_parameter_tag(url)>(url)
/**
* \def CROW_BP_ROUTE(blueprint, url)
* \brief Creates a route for a blueprint using a rule.
*
* It may use crow::Blueprint::new_rule_dynamic or
* crow::Blueprint::new_rule_tagged to define a new rule for an
* given blueprint. It's usage is similar to CROW_ROUTE macro:
*
* ```cpp
* crow::Blueprint my_bp();
* CROW_BP_ROUTE(my_bp, "/")
* ([](){
* return "<h1>Hello, world!</h1>";
* });
* ```
*
* This is the recommended way to define routes in a crow blueprint
* because of its compile-time capabilities.
*
* \see [Page of the guide "Blueprints"](https://crowcpp.org/master/guides/blueprints/).
*/
#define CROW_BP_ROUTE(blueprint, url) blueprint.new_rule_tagged<crow::black_magic::get_parameter_tag(url)>(url)
/**
* \def CROW_WEBSOCKET_ROUTE(app, url)
* \brief Defines WebSocket route for app.
*
* It binds a WebSocket route to app.
* for more information about how implement WebSockets in your
* application. The usage syntax of this macro is like this:
*
* ```cpp
* auto app = crow::SimpleApp(); // or crow::App()
* CROW_WEBSOCKET_ROUTE(app, "/ws")
* .onopen([&](crow::websocket::connection& conn){
* do_something();
* })
* .onclose([&](crow::websocket::connection& conn, const std::string& reason){
* do_something();
* })
* .onmessage([&](crow::websocket::connection&, const std::string& data, bool is_binary){
* if (is_binary)
* do_something(data);
* else
* do_something_else(data);
* });
* ```
*
* \see [Page of the guide "WebSockets"](https://crowcpp.org/master/guides/websockets/).
*/
#define CROW_WEBSOCKET_ROUTE(app, url) app.route<crow::black_magic::get_parameter_tag(url)>(url).websocket<std::remove_reference<decltype(app)>::type>(&app)
/**
* \def CROW_MIDDLEWARES(app, ...)
* \brief Enable a Middleware for an specific route in app
* or blueprint.
*
* It defines the usage of a Middleware in one route. And it
* can be used in both crow::SimpleApp (and crow::App)
* instances and crow::Blueprint. Its usage syntax is like this:
*
* ```cpp
* auto app = crow::SimpleApp(); // or crow::App()
* CROW_ROUTE(app, "/with_middleware")
* .CROW_MIDDLEWARES(app, LocalMiddleware) // Can be used more than one
* ([]() { // middleware.
* return "Hello world!";
* });
* ```
*
* \see [Page of the guide "Middlewares"](https://crowcpp.org/master/guides/middleware/).
*/
#define CROW_MIDDLEWARES(app, ...) template middlewares<typename std::remove_reference<decltype(app)>::type, __VA_ARGS__>()
#endif
#endif // #ifdef CROW_MSVC_WORKAROUND
/**
* \def CROW_CATCHALL_ROUTE(app)
* \brief Defines a custom catchall route for app using a
* custom rule.
*
* It defines a handler when the client make a request for an
* undefined route. Instead of just reply with a `404` status
* code (default behavior), you can define a custom handler
* using this macro.
*
* \see [Page of the guide "Routes" (Catchall routes)](https://crowcpp.org/master/guides/routes/#catchall-routes).
*/
#define CROW_CATCHALL_ROUTE(app) app.catchall_route()
/**
* \def CROW_BP_CATCHALL_ROUTE(blueprint)
* \brief Defines a custom catchall route for blueprint
* using a custom rule.
*
* It defines a handler when the client make a request for an
* undefined route in the blueprint.
*
* \see [Page of the guide "Blueprint" (Define a custom Catchall route)](https://crowcpp.org/master/guides/blueprints/#define-a-custom-catchall-route).
*/
#define CROW_BP_CATCHALL_ROUTE(blueprint) blueprint.catchall_rule()
/**
* \namespace crow
* \brief The main namespace. In this namespace are the most important
* classes and functions of the library.
*
* Within this namespace, the Crow class is defined, whose instances
* represent web applications with routes and rules.
*/
namespace crow
{
#ifdef CROW_ENABLE_SSL
using ssl_context_t = asio::ssl::context;
#endif
/// The main server application
///
/// Use `SimpleApp` or `App<Middleware1, Middleware2, etc...>`
/**
* \class Crow
* \brief The main server application class.
*
* Use SimpleApp or App<Middleware1, Middleware2, etc...> instead of
* directly instantiate this class.
*/
template<typename... Middlewares>
class Crow
{
public:
/// This crow application
/// \brief This is the crow application
using self_t = Crow;
/// The HTTP server
/// \brief The HTTP server
using server_t = Server<Crow, SocketAdaptor, Middlewares...>;
#ifdef CROW_ENABLE_SSL
/// An HTTP server that runs on SSL with an SSLAdaptor
/// \brief An HTTP server that runs on SSL with an SSLAdaptor
using ssl_server_t = Server<Crow, SSLAdaptor, Middlewares...>;
#endif
Crow()
{}
/// Construct Crow with a subset of middleware
/// \brief Construct Crow with a subset of middleware
template<typename... Ts>
Crow(Ts&&... ts):
middlewares_(make_middleware_tuple(std::forward<Ts>(ts)...))
{}
/// Process an Upgrade request
/// \brief Process an Upgrade request
///
/// Currently used to upgrade an HTTP connection to a WebSocket connection
template<typename Adaptor>
@ -76,19 +207,19 @@ namespace crow
router_.handle_upgrade(req, res, adaptor);
}
/// Process only the method and URL of a request and provide a route (or an error response)
/// \brief Process only the method and URL of a request and provide a route (or an error response)
std::unique_ptr<routing_handle_result> handle_initial(request& req, response& res)
{
return router_.handle_initial(req, res);
}
/// Process the fully parsed request and generate a response for it
/// \brief Process the fully parsed request and generate a response for it
void handle(request& req, response& res, std::unique_ptr<routing_handle_result>& found)
{
router_.handle<self_t>(req, res, *found);
}
/// Process a fully parsed request from start to finish (primarily used for debugging)
/// \brief Process a fully parsed request from start to finish (primarily used for debugging)
void handle_full(request& req, response& res)
{
auto found = handle_initial(req, res);
@ -96,13 +227,13 @@ namespace crow
handle(req, res, found);
}
/// Create a dynamic route using a rule (**Use CROW_ROUTE instead**)
/// \brief Create a dynamic route using a rule (**Use CROW_ROUTE instead**)
DynamicRule& route_dynamic(const std::string& rule)
{
return router_.new_rule_dynamic(rule);
}
/// Create a route using a rule (**Use CROW_ROUTE instead**)
/// \brief Create a route using a rule (**Use CROW_ROUTE instead**)
template<uint64_t Tag>
#ifdef CROW_GCC83_WORKAROUND
auto& route(const std::string& rule)
@ -118,89 +249,92 @@ namespace crow
return router_.new_rule_tagged<Tag>(rule);
}
/// Create a route for any requests without a proper route (**Use CROW_CATCHALL_ROUTE instead**)
/// \brief Create a route for any requests without a proper route (**Use CROW_CATCHALL_ROUTE instead**)
CatchallRule& catchall_route()
{
return router_.catchall_rule();
}
/// Set the default max payload size for websockets
/// \brief Set the default max payload size for websockets
self_t& websocket_max_payload(uint64_t max_payload)
{
max_payload_ = max_payload;
return *this;
}
/// Get the default max payload size for websockets
/// \brief Get the default max payload size for websockets
uint64_t websocket_max_payload()
{
return max_payload_;
}
/// \brief (TODO)
self_t& signal_clear()
{
signals_.clear();
return *this;
}
/// \brief (TODO)
self_t& signal_add(int signal_number)
{
signals_.push_back(signal_number);
return *this;
}
/// \brief (TODO)
std::vector<int> signals()
{
return signals_;
}
/// Set the port that Crow will handle requests on
/// \brief Set the port that Crow will handle requests on
self_t& port(std::uint16_t port)
{
port_ = port;
return *this;
}
/// Get the port that Crow will handle requests on
/// \brief Get the port that Crow will handle requests on
std::uint16_t port()
{
return port_;
}
/// Set the connection timeout in seconds (default is 5)
/// \brief Set the connection timeout in seconds (default is 5)
self_t& timeout(std::uint8_t timeout)
{
timeout_ = timeout;
return *this;
}
/// Set the server name
/// \brief Set the server name
self_t& server_name(std::string server_name)
{
server_name_ = server_name;
return *this;
}
/// The IP address that Crow will handle requests on (default is 0.0.0.0)
/// \brief The IP address that Crow will handle requests on (default is 0.0.0.0)
self_t& bindaddr(std::string bindaddr)
{
bindaddr_ = bindaddr;
return *this;
}
/// Get the address that Crow will handle requests on
/// \brief Get the address that Crow will handle requests on
std::string bindaddr()
{
return bindaddr_;
}
/// Run the server on multiple threads using all available threads
/// \brief Run the server on multiple threads using all available threads
self_t& multithreaded()
{
return concurrency(std::thread::hardware_concurrency());
}
/// Run the server on multiple threads using a specific number
/// \brief Run the server on multiple threads using a specific number
self_t& concurrency(std::uint16_t concurrency)
{
if (concurrency < 2) // Crow can have a minimum of 2 threads running
@ -209,29 +343,27 @@ namespace crow
return *this;
}
/// Get the number of threads that server is using
/// \brief Get the number of threads that server is using
std::uint16_t concurrency()
{
return concurrency_;
}
/// Set the server's log level
/// \brief Set the server's log level
///
/// Possible values are:<br>
/// crow::LogLevel::Debug (0)<br>
/// crow::LogLevel::Info (1)<br>
/// crow::LogLevel::Warning (2)<br>
/// crow::LogLevel::Error (3)<br>
/// crow::LogLevel::Critical (4)<br>
/// Possible values are:
/// - crow::LogLevel::Debug (0)
/// - crow::LogLevel::Info (1)
/// - crow::LogLevel::Warning (2)
/// - crow::LogLevel::Error (3)
/// - crow::LogLevel::Critical (4)
self_t& loglevel(LogLevel level)
{
crow::logger::setLogLevel(level);
return *this;
}
/// Set the response body size (in bytes) beyond which Crow automatically streams responses (Default is 1MiB)
/// \brief Set the response body size (in bytes) beyond which Crow automatically streams responses (Default is 1MiB)
///
/// Any streamed response is unaffected by Crow's timer, and therefore won't timeout before a response is fully sent.
self_t& stream_threshold(size_t threshold)
@ -240,7 +372,7 @@ namespace crow
return *this;
}
/// Get the response body size (in bytes) beyond which Crow automatically streams responses
/// \brief Get the response body size (in bytes) beyond which Crow automatically streams responses
size_t& stream_threshold()
{
return res_stream_threshold_;
@ -252,8 +384,7 @@ namespace crow
return *this;
}
/// Set the function to call to handle uncaught exceptions generated in routes (Default generates error 500).
/// \brief Set the function to call to handle uncaught exceptions generated in routes (Default generates error 500).
///
/// The function must have the following signature: void(crow::response&).
/// It must set the response passed in argument to the function, which will be sent back to the client.
@ -265,12 +396,13 @@ namespace crow
return *this;
}
/// \brief (TODO)
std::function<void(crow::response&)>& exception_handler()
{
return router_.exception_handler();
}
/// Set a custom duration and function to run on every tick
/// \brief Set a custom duration and function to run on every tick
template<typename Duration, typename Func>
self_t& tick(Duration d, Func f)
{
@ -280,6 +412,7 @@ namespace crow
}
#ifdef CROW_ENABLE_COMPRESSION
/// \brief (TODO)
self_t& use_compression(compression::algorithm algorithm)
{
comp_algorithm_ = algorithm;
@ -287,18 +420,20 @@ namespace crow
return *this;
}
/// \brief (TODO)
compression::algorithm compression_algorithm()
{
return comp_algorithm_;
}
/// \brief (TODO)
bool compression_used() const
{
return compression_used_;
}
#endif
/// Apply blueprints
/// \brief Apply blueprints
void add_blueprint()
{
#if defined(__APPLE__) || defined(__MACH__)
@ -321,7 +456,7 @@ namespace crow
router_.validate_bp();
}
/// Go through the rules, upgrade them if possible, and add them to the list of rules
/// \brief Go through the rules, upgrade them if possible, and add them to the list of rules
void add_static_dir()
{
if (are_static_routes_added()) return;
@ -335,13 +470,13 @@ namespace crow
set_static_routes_added();
}
/// A wrapper for `validate()` in the router
/// \brief A wrapper for `validate()` in the router
void validate()
{
router_.validate();
}
/// Run the server
/// \brief Run the server
void run()
{
#ifndef CROW_DISABLE_STATIC_DIR
@ -377,7 +512,7 @@ namespace crow
}
}
/// Non-blocking version of \ref run()
/// \brief Non-blocking version of \ref run()
///
/// The output from this method needs to be saved into a variable!
/// Otherwise the call will be made on the same thread.
@ -388,7 +523,7 @@ namespace crow
});
}
/// Stop the server
/// \brief Stop the server
void stop()
{
#ifdef CROW_ENABLE_SSL
@ -410,17 +545,19 @@ namespace crow
}
}
/// \brief (TODO)
void add_websocket(crow::websocket::connection* conn)
{
websockets_.push_back(conn);
}
/// \brief (TODO)
void remove_websocket(crow::websocket::connection* conn)
{
websockets_.erase(std::remove(websockets_.begin(), websockets_.end(), conn), websockets_.end());
}
/// Print the routing paths defined for each HTTP method
/// \brief Print the routing paths defined for each HTTP method
void debug_print()
{
CROW_LOG_DEBUG << "Routing:";
@ -430,7 +567,7 @@ namespace crow
#ifdef CROW_ENABLE_SSL
/// Use certificate and key files for SSL
/// \brief Use certificate and key files for SSL
self_t& ssl_file(const std::string& crt_filename, const std::string& key_filename)
{
ssl_used_ = true;
@ -443,7 +580,7 @@ namespace crow
return *this;
}
/// Use .pem file for SSL
/// \brief Use `.pem` file for SSL
self_t& ssl_file(const std::string& pem_filename)
{
ssl_used_ = true;
@ -455,7 +592,7 @@ namespace crow
return *this;
}
/// Use certificate chain and key files for SSL
/// \brief Use certificate chain and key files for SSL
self_t& ssl_chainfile(const std::string& crt_filename, const std::string& key_filename)
{
ssl_used_ = true;
@ -468,6 +605,7 @@ namespace crow
return *this;
}
/// \brief (TODO)
self_t& ssl(asio::ssl::context&& ctx)
{
ssl_used_ = true;
@ -475,11 +613,13 @@ namespace crow
return *this;
}
/// \brief (TODO)
bool ssl_used() const
{
return ssl_used_;
}
#else
/// \brief (TODO)
template<typename T, typename... Remain>
self_t& ssl_file(T&&, Remain&&...)
{
@ -491,6 +631,7 @@ namespace crow
return *this;
}
/// \brief (TODO)
template<typename T, typename... Remain>
self_t& ssl_chainfile(T&&, Remain&&...)
{
@ -502,6 +643,7 @@ namespace crow
return *this;
}
/// \brief (TODO)
template<typename T>
self_t& ssl(T&&)
{
@ -513,6 +655,7 @@ namespace crow
return *this;
}
/// \brief (TODO)
bool ssl_used() const
{
return false;
@ -530,13 +673,14 @@ namespace crow
return ctx.template get<T>();
}
/// \brief (TODO)
template<typename T>
T& get_middleware()
{
return utility::get_element_by_type<T, Middlewares...>(middlewares_);
}
/// Wait until the server has properly started
/// \brief Wait until the server has properly started
void wait_for_server_start()
{
{
@ -553,6 +697,7 @@ namespace crow
}
private:
/// \brief TODO (But it's not so necessary).
template<typename... Ts>
std::tuple<Middlewares...> make_middleware_tuple(Ts&&... ts)
{
@ -562,7 +707,7 @@ namespace crow
black_magic::tuple_extract<Middlewares, decltype(fwd)>(fwd))...);
}
/// Notify anything using `wait_for_server_start()` to proceed
/// \brief Notify anything using \ref wait_for_server_start() to proceed
void notify_server_start()
{
std::unique_lock<std::mutex> lock(start_mutex_);
@ -570,10 +715,12 @@ namespace crow
cv_started_.notify_all();
}
/// \brief TODO (But it's not so necessary).
void set_static_routes_added() {
static_routes_added_ = true;
}
/// \brief TODO (But it's not so necessary).
bool are_static_routes_added() {
return static_routes_added_;
}
@ -614,7 +761,13 @@ namespace crow
std::mutex start_mutex_;
std::vector<crow::websocket::connection*> websockets_;
};
/// \brief Alias of Crow<Middlewares...>. Useful if you want
/// a instance of an Crow application that require Middlewares
template<typename... Middlewares>
using App = Crow<Middlewares...>;
/// \brief Alias of Crow<>. Useful if you want a instance of
/// an Crow application that doesn't require of Middlewares
using SimpleApp = Crow<>;
} // namespace crow

2
include/crow/http_request.h
View File

@ -13,7 +13,7 @@
#include "crow/ci_map.h"
#include "crow/query_string.h"
namespace crow
namespace crow // NOTE: Already documented in "crow/app.h"
{
#ifdef CROW_USE_BOOST
namespace asio = boost::asio;

3
include/crow/http_server.h
View File

@ -27,7 +27,8 @@
#include "crow/logging.h"
#include "crow/task_timer.h"
namespace crow
namespace crow // NOTE: Already documented in "crow/app.h"
{
#ifdef CROW_USE_BOOST
namespace asio = boost::asio;

4
include/crow/middleware.h
View File

@ -18,6 +18,10 @@ namespace crow
using call_global = std::false_type;
};
/**
* \namespace detail
* \brief TODO
*/
namespace detail
{
template<typename MW>