Struct Server 

#[non_exhaustive]
pub struct Server { /* private fields */ }

The central application server builder for Rullst.

Configures and boots the Axum HTTP server, optional ORM connection pool, task scheduler, hot-reload DLL watcher, traffic shield, and rate limiter in a single fluent chain.

Example

use rullst_core::{Server, routes, routing::get};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    Server::new(routes![get("/" => || async { "OK" })])
        .run(3000)
        .await?;
    Ok(())
}

Implementations

impl Server

pub fn new(router: Router) -> Self

Creates a new Server from an already-built Router. Use Server::new_hot instead to enable hot-reload mode.

pub fn new_hot<S: Into<String>>(lib_path: S) -> Self

Creates a Server in hot-reload mode that loads the application router from a compiled cdylib dynamic library at the given lib_path. The background file-watcher recompiles and hot-swaps the router on source changes.

pub fn with_machine_endpoints(self, policy: MachineEndpointPolicy) -> Self

Requires explicit machine authentication before CSRF exemptions on exact routes.

pub fn with_db<S: Into<String>>(self, db_url: S) -> Self

Sets a database URL to initialize the ORM connection pool at startup.

This requires the orm feature. When Core is compiled without orm, configuring a database remains a valid builder operation but Self::run fails closed with ServerError::Database.

pub fn schedule(self, scheduler: Scheduler) -> Self

Attach a task scheduler that runs alongside the HTTP server.

The server owns the scheduler handle: every task failure is logged as a tracing error on the rullst::scheduler target when it is reported, and task failures never make a clean shutdown fail. Only a failed scheduler loop is returned as ServerError::Scheduler.

Example

use rullst_core::{Server, Scheduler, routes, routing::get};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let scheduler = Scheduler::new()
        .task("0 0 * * *", || async { println!("daily cleanup"); })?;
    let router = routes![get("/" => || async { "OK" })];

    Server::new(router)
        .schedule(scheduler)
        .run(3000)
        .await?;
    Ok(())
}

pub fn shield(self, shield: TrafficShield) -> Self

Attaches an adaptive TrafficShield to the server to protect against CPU/DB saturation.

Exact GET/HEAD /health and /ready probes are never shed.

pub fn rate_limit(self, limiter: RateLimiter) -> Self

Attaches a global RateLimiter to the server.

Exact GET/HEAD /health and /ready probes do not consume tokens.

pub fn with_lifecycle(self, lifecycle: ApplicationLifecycle) -> Self

Attaches a shared readiness and graceful-drain coordinator.

Static and development hot-reload requests are admitted only while this lifecycle and all of its required components are ready. Exact health probes remain reachable. Mount crate::health::health_router_with_lifecycle with a clone to expose the same aggregate state to an orchestrator.

pub async fn run(self, port: u16) -> Result<(), ServerError>

Start the HTTP server on the specified port

pub async fn run_with_shutdown<F>( self, port: u16, shutdown: F, ) -> Result<(), ServerError>

where F: Future<Output = ()> + Send + 'static,

Starts the HTTP server with a caller-supplied graceful-shutdown future.

This is useful for embedded process supervisors and deterministic tests. Resolving the future begins lifecycle draining before Axum waits for already accepted requests. Self::run remains the OS-signal default.