|
Orbit Framework 2.0.0
A high-performance asynchronous C++20 HTTP server framework.
|
The main application class for the Orbit Framework. More...
#include <App.hpp>

Public Member Functions | |
| App (const config::ServerConfig &config) | |
| Constructs a new App instance. | |
| ~App () | |
| App (const App &)=delete | |
| App & | operator= (const App &)=delete |
| void | on_error (routing::ErrorHandler handler) |
| Registers a global error handler for the application. | |
| App & | use (routing::Middleware m) |
| Registers a global middleware. | |
| App & | use (const std::string &prefix, routing::Middleware m) |
Runs m only for requests under prefix ("/api" and "/api/..."). | |
| App & | not_found (routing::RouteHandler handler) |
| Answers requests that match no route instead of "404 Not Found". | |
| App & | group (const std::string &prefix, std::function< void(routing::Router &)> callback) |
| Creates a route group with a specific prefix. | |
| routing::Router::RouteBuilder | route (const std::string &path, http::HttpMethod method=http::HttpMethod::GET) |
| Initiates a route builder for a specific path and method. | |
| App & | get (const std::string &path, routing::RouteHandler handler) |
| Registers a GET route. | |
| App & | get (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers a GET route with middleware. | |
| App & | post (const std::string &path, routing::RouteHandler handler) |
| Registers a POST route. | |
| App & | post (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers a POST route with middleware. | |
| App & | put (const std::string &path, routing::RouteHandler handler) |
| Registers a PUT route. | |
| App & | put (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers a PUT route with middleware. | |
| App & | patch (const std::string &path, routing::RouteHandler handler) |
| Registers a PATCH route. | |
| App & | patch (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers a PATCH route with middleware. | |
| App & | del (const std::string &path, routing::RouteHandler handler) |
| Registers a DELETE route. | |
| App & | del (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers a DELETE route with middleware. | |
| App & | options (const std::string &path, routing::RouteHandler handler) |
| Registers an OPTIONS route. | |
| App & | options (const std::string &path, std::vector< routing::Middleware > mws, routing::RouteHandler handler) |
| Registers an OPTIONS route with middleware. | |
| template<typename Handler > | |
| App & | get (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | get (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| template<typename Handler > | |
| App & | post (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | post (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| template<typename Handler > | |
| App & | put (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | put (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| template<typename Handler > | |
| App & | patch (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | patch (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| template<typename Handler > | |
| App & | del (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | del (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| template<typename Handler > | |
| App & | options (const std::string &path, Handler &&handler) |
| template<typename Handler > | |
| App & | options (const std::string &path, std::vector< routing::Middleware > mws, Handler &&handler) |
| App & | ws (const std::string &path, std::vector< routing::Middleware > mws, routing::WsHandler handler) |
| Registers a WebSocket route. | |
| App & | ws (const std::string &path, routing::WsHandler handler) |
| std::vector< size_t > | connections_per_event_loop () const |
| Retrieves the application's thread pool. | |
| const config::ServerConfig & | effective_config () const |
| The configuration in effect: once listen() has started, "auto" settings (event_loops = 0, worker_threads = 0, EventEngine::Auto) show what they resolved to. | |
| concurrency::ThreadPool & | get_thread_pool () |
| openapi::OpenApiRegistry & | openapi () |
| This app's OpenAPI registry: its routes, plus schemas added with openapi().register_schema(). Each App has its own, so two Apps in one process publish separate specs. | |
| const routing::Router & | router () const |
| The router every request goes through (orbit::testing::Client uses it). | |
| std::vector< std::string > | validate_routes () const |
| App & | enable_metrics (const std::string &path="/metrics") |
| Enables Prometheus metrics endpoint. | |
| App & | on_start (std::function< void(App &)> hook) |
Runs hook once the server is up: listeners bound, worker pool and timers running, just before the event loops start serving. On a worker thread, so it may block or be a coroutine (warm a cache, connect a pool, run migrate_sync()). | |
| App & | on_stop (std::function< void(App &)> hook) |
Runs hook once when the server stops: at the first shutdown() (or SIGTERM/SIGINT) before connections drain, at stop(), or when listen() returns. Only for a server that started. Runs on the thread that stops the server, which may be the event loop: keep it short (flush a queue, deregister). | |
| TimerHandle | run_every (std::chrono::milliseconds interval, std::function< void()> callback) |
Calls callback every interval, on a worker thread, from when the server starts (or now, if it is running) until it stops or the handle is cancelled. | |
| TimerHandle | run_after (std::chrono::milliseconds delay, std::function< void()> callback) |
| App & | enable_openapi (const std::string &title="Orbit Framework API", const std::string &version="1.0.0", const std::string &docs_path="/docs", const std::string &json_path="/swagger.json", const std::string &assets_url="https://unpkg.com/swagger-ui-dist@5.11.0") |
| Enables OpenAPI documentation and Swagger UI. | |
| void | listen () |
| Starts the server and blocks the current thread. | |
| void | stop () |
| Stops the server immediately: open connections are dropped. Safe to call from any thread, even before listen(). | |
| void | shutdown () |
Stops the server gracefully (what SIGTERM/SIGINT do): stop accepting, mark the app not ready, let in-flight requests finish, close idle connections, and force-close the rest after timeout (default: ServerConfig::shutdown_timeout). listen() returns when done. Safe to call from any thread. | |
| bool | reload_tls (std::string *error=nullptr) |
| Re-reads the TLS certificate and key files (ssl_cert, ssl_key and sni_certificates). Thread-safe; also triggered by SIGHUP and by ServerConfig::tls_reload_interval. | |
| void | shutdown (std::chrono::seconds timeout) |
| App & | enable_health_checks (const std::string &liveness="/healthz", const std::string &readiness="/readyz") |
Adds health endpoints for orchestrators such as Kubernetes: liveness answers 200 while the process runs; readiness answers 200 while serving and 503 once shutdown has begun, so load balancers stop sending new traffic. | |
| bool | is_draining () const |
| True once shutdown() (or SIGTERM/SIGINT) has started draining. | |
| void | hot_reload () |
| Triggers a hot reload of the server configuration and routes. | |
Private Member Functions | |
| void | run_stop_hooks () |
Private Attributes | |
| config::ServerConfig | config_ |
| routing::Router | router_ |
| std::vector< std::unique_ptr< Listener > > | listeners_ |
| std::unique_ptr< network::TlsContext > | tls_context_ |
| std::atomic< size_t > | open_connections_ {0} |
| std::vector< std::unique_ptr< EventLoop > > | event_loops_ |
| std::vector< std::thread > | loop_threads_ |
| std::unique_ptr< concurrency::ThreadPool > | thread_pool_ |
| std::unique_ptr< Scheduler > | scheduler_ |
| std::vector< std::function< void(App &)> > | start_hooks_ |
| std::vector< std::function< void(App &)> > | stop_hooks_ |
| std::atomic< bool > | started_ {false} |
| std::atomic< bool > | stop_hooks_ran_ {false} |
| std::mutex | loop_mutex_ |
| bool | stop_requested_ = false |
| unsigned | seen_signal_seq_ = 0 |
| std::chrono::steady_clock::time_point | next_tls_check_ {} |
| std::atomic< bool > | draining_ {false} |
The main application class for the Orbit Framework.
The App class acts as the central orchestrator for the web framework. It manages the server's lifecycle, routing, middlewares, dependency injection, and worker thread pools. Users instantiate this class, define their routes, and call listen() to start accepting connections.
| orbit::server::App::App | ( | const config::ServerConfig & | config | ) |
Constructs a new App instance.
| config | The server configuration containing port, worker threads, and event engine preferences. |
| orbit::server::App::~App | ( | ) |
|
delete |
| std::vector< size_t > orbit::server::App::connections_per_event_loop | ( | ) | const |
Retrieves the application's thread pool.
| std::runtime_error | If the server is not started. |
Open connections on each event loop (one entry per loop; empty before listen()). See ServerConfig::event_loops.
|
inline |
| App & orbit::server::App::del | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers a DELETE route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::del | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers a DELETE route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
|
inline |
The configuration in effect: once listen() has started, "auto" settings (event_loops = 0, worker_threads = 0, EventEngine::Auto) show what they resolved to.
| App & orbit::server::App::enable_health_checks | ( | const std::string & | liveness = "/healthz", |
| const std::string & | readiness = "/readyz" |
||
| ) |
Adds health endpoints for orchestrators such as Kubernetes: liveness answers 200 while the process runs; readiness answers 200 while serving and 503 once shutdown has begun, so load balancers stop sending new traffic.
| App & orbit::server::App::enable_metrics | ( | const std::string & | path = "/metrics" | ) |
Enables Prometheus metrics endpoint.
Metrics are process-wide, as in other Prometheus clients: with several Apps in one process, each endpoint reports the same totals.
| path | The URL path for metrics (default is "/metrics"). |
| App & orbit::server::App::enable_openapi | ( | const std::string & | title = "Orbit Framework API", |
| const std::string & | version = "1.0.0", |
||
| const std::string & | docs_path = "/docs", |
||
| const std::string & | json_path = "/swagger.json", |
||
| const std::string & | assets_url = "https://unpkg.com/swagger-ui-dist@5.11.0" |
||
| ) |
Enables OpenAPI documentation and Swagger UI.
| title | The API title. |
| version | The API version. |
| docs_path | The URL path for Swagger UI. |
| json_path | The URL path for the OpenAPI JSON. |
| assets_url | Where the Swagger UI files (swagger-ui.css and swagger-ui-bundle.js from swagger-ui-dist 5.11.0) are loaded from. Defaults to the unpkg CDN; point it at your own copy (e.g. "/swagger-ui" served by static_files) to keep the docs page off third-party origins. Either way the page pins the files with Subresource Integrity hashes, so modified files are refused by the browser. |
The docs page is only registered when this is called; enable it only in environments where the API description may be public. Its bootstrap script is served at docs_path + "/init.js", never inline, so the page works under a Content-Security-Policy that allows scripts from 'self' and the asset origin.
|
inline |
| App & orbit::server::App::get | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers a GET route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::get | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers a GET route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
|
inline |
|
inline |
Creates a route group with a specific prefix.
| prefix | The URL prefix for the group. |
| callback | A function to configure routes within the group. |
| void orbit::server::App::hot_reload | ( | ) |
Triggers a hot reload of the server configuration and routes.
|
inline |
True once shutdown() (or SIGTERM/SIGINT) has started draining.
| void orbit::server::App::listen | ( | ) |
Starts the server and blocks the current thread.
| App & orbit::server::App::not_found | ( | routing::RouteHandler | handler | ) |
Answers requests that match no route instead of "404 Not Found".
| void orbit::server::App::on_error | ( | routing::ErrorHandler | handler | ) |
Registers a global error handler for the application.
| handler | The error handler function. |
Runs hook once the server is up: listeners bound, worker pool and timers running, just before the event loops start serving. On a worker thread, so it may block or be a coroutine (warm a cache, connect a pool, run migrate_sync()).
Hooks run in the order added. One that throws is logged and the others still run; call app.stop() or app.shutdown() from a hook to abort start-up instead.
Runs hook once when the server stops: at the first shutdown() (or SIGTERM/SIGINT) before connections drain, at stop(), or when listen() returns. Only for a server that started. Runs on the thread that stops the server, which may be the event loop: keep it short (flush a queue, deregister).
|
inline |
|
inline |
| App & orbit::server::App::options | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers an OPTIONS route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::options | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers an OPTIONS route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::patch | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers a PATCH route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::patch | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers a PATCH route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::post | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers a POST route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::post | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers a POST route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::put | ( | const std::string & | path, |
| routing::RouteHandler | handler | ||
| ) |
Registers a PUT route.
| path | The URL path. |
| handler | The route handler function. |
|
inline |
| App & orbit::server::App::put | ( | const std::string & | path, |
| std::vector< routing::Middleware > | mws, | ||
| routing::RouteHandler | handler | ||
| ) |
Registers a PUT route with middleware.
| path | The URL path. |
| mws | A vector of middlewares to apply. |
| handler | The route handler function. |
| bool orbit::server::App::reload_tls | ( | std::string * | error = nullptr | ) |
Re-reads the TLS certificate and key files (ssl_cert, ssl_key and sni_certificates). Thread-safe; also triggered by SIGHUP and by ServerConfig::tls_reload_interval.
New handshakes use the new certificates; open connections are not affected. If any file fails to load, the current certificates stay.
error).
|
inline |
Initiates a route builder for a specific path and method.
| path | The URL path. |
| method | The HTTP method (default is GET). |
|
inline |
The router every request goes through (orbit::testing::Client uses it).
| TimerHandle orbit::server::App::run_after | ( | std::chrono::milliseconds | delay, |
| std::function< void()> | callback | ||
| ) |
Calls callback once, delay after the server starts (or after now, if it is running), on a worker thread.
| TimerHandle orbit::server::App::run_every | ( | std::chrono::milliseconds | interval, |
| std::function< void()> | callback | ||
| ) |
Calls callback every interval, on a worker thread, from when the server starts (or now, if it is running) until it stops or the handle is cancelled.
Runs never overlap: a tick that comes while the previous run is still going is skipped. An exception from the callback is logged.
|
private |
| void orbit::server::App::shutdown | ( | ) |
Stops the server gracefully (what SIGTERM/SIGINT do): stop accepting, mark the app not ready, let in-flight requests finish, close idle connections, and force-close the rest after timeout (default: ServerConfig::shutdown_timeout). listen() returns when done. Safe to call from any thread.
| void orbit::server::App::shutdown | ( | std::chrono::seconds | timeout | ) |
| void orbit::server::App::stop | ( | ) |
Stops the server immediately: open connections are dropped. Safe to call from any thread, even before listen().
| App & orbit::server::App::use | ( | const std::string & | prefix, |
| routing::Middleware | m | ||
| ) |
Runs m only for requests under prefix ("/api" and "/api/...").
Runs before route matching, so it can handle paths without a route, e.g. app.use("/api", orbit::middleware::proxy(opts)).
| App & orbit::server::App::use | ( | routing::Middleware | m | ) |
Registers a global middleware.
| m | The middleware function. |
|
inline |
Router::validate_routes(), to check for duplicate routes without calling listen() (which throws std::invalid_argument on its own if any are found).
|
inline |
|
inline |
Registers a WebSocket route.
| path | The URL path. |
| handler | The WebSocket handler function. |
|
private |
|
private |
|
private |
|
private |
|
mutableprivate |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |
|
private |