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

The main application class for the Orbit Framework. More...

#include <App.hpp>

Collaboration diagram for orbit::server::App:

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}
 

Detailed Description

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.

Examples
/home/runner/work/orbit-framework/orbit-framework/include/orbit/websocket/EventRouter.hpp.

Constructor & Destructor Documentation

◆ App() [1/2]

orbit::server::App::App ( const config::ServerConfig &  config)

Constructs a new App instance.

Parameters
configThe server configuration containing port, worker threads, and event engine preferences.

◆ ~App()

orbit::server::App::~App ( )

◆ App() [2/2]

orbit::server::App::App ( const App &  )
delete

Member Function Documentation

◆ connections_per_event_loop()

std::vector< size_t > orbit::server::App::connections_per_event_loop ( ) const

Retrieves the application's thread pool.

Returns
Reference to the ThreadPool.
Exceptions
std::runtime_errorIf the server is not started.

Open connections on each event loop (one entry per loop; empty before listen()). See ServerConfig::event_loops.

◆ del() [1/4]

template<typename Handler >
App & orbit::server::App::del ( const std::string &  path,
Handler &&  handler 
)
inline

◆ del() [2/4]

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

Registers a DELETE route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ del() [3/4]

template<typename Handler >
App & orbit::server::App::del ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ del() [4/4]

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

Registers a DELETE route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ effective_config()

const config::ServerConfig & orbit::server::App::effective_config ( ) const
inline

The configuration in effect: once listen() has started, "auto" settings (event_loops = 0, worker_threads = 0, EventEngine::Auto) show what they resolved to.

◆ enable_health_checks()

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.

◆ enable_metrics()

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.

Parameters
pathThe URL path for metrics (default is "/metrics").
Returns
Reference to the App instance for chaining.

◆ enable_openapi()

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.

Parameters
titleThe API title.
versionThe API version.
docs_pathThe URL path for Swagger UI.
json_pathThe URL path for the OpenAPI JSON.
assets_urlWhere 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.
Returns
Reference to the App instance for chaining.

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.

◆ get() [1/4]

template<typename Handler >
App & orbit::server::App::get ( const std::string &  path,
Handler &&  handler 
)
inline

◆ get() [2/4]

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

Registers a GET route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ get() [3/4]

template<typename Handler >
App & orbit::server::App::get ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ get() [4/4]

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

Registers a GET route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ get_thread_pool()

concurrency::ThreadPool & orbit::server::App::get_thread_pool ( )
inline

◆ group()

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

Creates a route group with a specific prefix.

Parameters
prefixThe URL prefix for the group.
callbackA function to configure routes within the group.
Returns
Reference to the App instance for chaining.

◆ hot_reload()

void orbit::server::App::hot_reload ( )

Triggers a hot reload of the server configuration and routes.

◆ is_draining()

bool orbit::server::App::is_draining ( ) const
inline

True once shutdown() (or SIGTERM/SIGINT) has started draining.

◆ listen()

void orbit::server::App::listen ( )

Starts the server and blocks the current thread.

◆ not_found()

App & orbit::server::App::not_found ( routing::RouteHandler  handler)

Answers requests that match no route instead of "404 Not Found".

◆ on_error()

void orbit::server::App::on_error ( routing::ErrorHandler  handler)

Registers a global error handler for the application.

Parameters
handlerThe error handler function.

◆ on_start()

App & orbit::server::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()).

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.

◆ on_stop()

App & orbit::server::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).

◆ openapi()

openapi::OpenApiRegistry & orbit::server::App::openapi ( )
inline

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.

◆ operator=()

App & orbit::server::App::operator= ( const App &  )
delete

◆ options() [1/4]

template<typename Handler >
App & orbit::server::App::options ( const std::string &  path,
Handler &&  handler 
)
inline

◆ options() [2/4]

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

Registers an OPTIONS route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ options() [3/4]

template<typename Handler >
App & orbit::server::App::options ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ options() [4/4]

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

Registers an OPTIONS route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ patch() [1/4]

template<typename Handler >
App & orbit::server::App::patch ( const std::string &  path,
Handler &&  handler 
)
inline

◆ patch() [2/4]

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

Registers a PATCH route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ patch() [3/4]

template<typename Handler >
App & orbit::server::App::patch ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ patch() [4/4]

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

Registers a PATCH route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ post() [1/4]

template<typename Handler >
App & orbit::server::App::post ( const std::string &  path,
Handler &&  handler 
)
inline

◆ post() [2/4]

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

Registers a POST route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ post() [3/4]

template<typename Handler >
App & orbit::server::App::post ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ post() [4/4]

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

Registers a POST route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ put() [1/4]

template<typename Handler >
App & orbit::server::App::put ( const std::string &  path,
Handler &&  handler 
)
inline

◆ put() [2/4]

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

Registers a PUT route.

Parameters
pathThe URL path.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ put() [3/4]

template<typename Handler >
App & orbit::server::App::put ( const std::string &  path,
std::vector< routing::Middleware >  mws,
Handler &&  handler 
)
inline

◆ put() [4/4]

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

Registers a PUT route with middleware.

Parameters
pathThe URL path.
mwsA vector of middlewares to apply.
handlerThe route handler function.
Returns
Reference to the App instance for chaining.

◆ reload_tls()

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.

Returns
False if TLS is off or loading failed (see error).

◆ route()

routing::Router::RouteBuilder orbit::server::App::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()

const routing::Router & orbit::server::App::router ( ) const
inline

The router every request goes through (orbit::testing::Client uses it).

◆ run_after()

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.

◆ run_every()

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.

auto heartbeat = app.run_every(std::chrono::seconds(15), [&hub] { hub.ping(); });

◆ run_stop_hooks()

void orbit::server::App::run_stop_hooks ( )
private

◆ shutdown() [1/2]

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.

◆ shutdown() [2/2]

void orbit::server::App::shutdown ( std::chrono::seconds  timeout)

◆ stop()

void orbit::server::App::stop ( )

Stops the server immediately: open connections are dropped. Safe to call from any thread, even before listen().

◆ use() [1/2]

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)).

◆ use() [2/2]

App & orbit::server::App::use ( routing::Middleware  m)

Registers a global middleware.

Parameters
mThe middleware function.
Returns
Reference to the App instance for chaining.

◆ validate_routes()

std::vector< std::string > orbit::server::App::validate_routes ( ) const
inline

Router::validate_routes(), to check for duplicate routes without calling listen() (which throws std::invalid_argument on its own if any are found).

◆ ws() [1/2]

App & orbit::server::App::ws ( const std::string &  path,
routing::WsHandler  handler 
)
inline

◆ ws() [2/2]

App & orbit::server::App::ws ( const std::string &  path,
std::vector< routing::Middleware >  mws,
routing::WsHandler  handler 
)
inline

Registers a WebSocket route.

Parameters
pathThe URL path.
handlerThe WebSocket handler function.
Returns
Reference to the App instance for chaining.
Examples
/home/runner/work/orbit-framework/orbit-framework/include/orbit/websocket/EventRouter.hpp.

Member Data Documentation

◆ config_

config::ServerConfig orbit::server::App::config_
private

◆ draining_

std::atomic<bool> orbit::server::App::draining_ {false}
private

◆ event_loops_

std::vector<std::unique_ptr<EventLoop> > orbit::server::App::event_loops_
private

◆ listeners_

std::vector<std::unique_ptr<Listener> > orbit::server::App::listeners_
private

◆ loop_mutex_

std::mutex orbit::server::App::loop_mutex_
mutableprivate

◆ loop_threads_

std::vector<std::thread> orbit::server::App::loop_threads_
private

◆ next_tls_check_

std::chrono::steady_clock::time_point orbit::server::App::next_tls_check_ {}
private

◆ open_connections_

std::atomic<size_t> orbit::server::App::open_connections_ {0}
private

◆ router_

routing::Router orbit::server::App::router_
private

◆ scheduler_

std::unique_ptr<Scheduler> orbit::server::App::scheduler_
private

◆ seen_signal_seq_

unsigned orbit::server::App::seen_signal_seq_ = 0
private

◆ start_hooks_

std::vector<std::function<void(App&)> > orbit::server::App::start_hooks_
private

◆ started_

std::atomic<bool> orbit::server::App::started_ {false}
private

◆ stop_hooks_

std::vector<std::function<void(App&)> > orbit::server::App::stop_hooks_
private

◆ stop_hooks_ran_

std::atomic<bool> orbit::server::App::stop_hooks_ran_ {false}
private

◆ stop_requested_

bool orbit::server::App::stop_requested_ = false
private

◆ thread_pool_

std::unique_ptr<concurrency::ThreadPool> orbit::server::App::thread_pool_
private

◆ tls_context_

std::unique_ptr<network::TlsContext> orbit::server::App::tls_context_
private

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