Struct WebServer 

pub struct WebServer<S = ()> { /* private fields */ }

An HTTP server.

Requires only an address, a port and an Environment. A sidecar that serves nothing but its health check is a valid server; a full site adds frontend. A single binary can run several of these and drain them from one Shutdown.

Implementations

impl WebServer<()>

pub fn new(host: impl Into<String>, port: u16, environment: Environment) -> Self

A server with no application state.

pub fn from_env() -> Result<Self, WebServerError>

A server with no application state, read entirely from the environment.

WSB_ENVIRONMENT is required. WSB_HOST defaults to 127.0.0.1 locally and 0.0.0.0 in production; WSB_PORT defaults to DEFAULT_PORT.

Errors

WebServerError::Env if a variable is missing or malformed.

impl<S> WebServer<S>

where S: Clone + Send + Sync + 'static,

pub fn with_state( host: impl Into<String>, port: u16, environment: Environment, app: S, ) -> Self

A server carrying application state.

pub fn from_env_with_state(app: S) -> Result<Self, WebServerError>

A server carrying application state, read entirely from the environment.

Errors

WebServerError::Env if a variable is missing or malformed.

pub const fn body_limit(self, body_limit: usize) -> Self

Caps request bodies. Defaults to DEFAULT_BODY_LIMIT.

The one size that genuinely varies: an image-upload endpoint and a landing page have nothing in common here.

pub fn root_dir(self, root_dir: impl Into<PathBuf>) -> Self

Where html/, static/ and cache-buster.json are read from. Defaults to the working directory.

Covers every file the server reads, at boot and per request. It does not move the build-time asset pipeline, which always runs in the working directory. Set it when the process cannot run from the built site: a cargo test runs from its crate’s directory, not from bin/.

pub fn nest(self, path: &str, router: Router<WebServerState<S>>) -> Self

Nests a router under path.

pub fn merge(self, router: Router<WebServerState<S>>) -> Self

Merges a router at the root.

pub fn nest_service<T>(self, path: &str, service: T) -> Self

where T: Service<Request, Error = Infallible> + Clone + Send + Sync + 'static, T::Response: IntoResponse, T::Future: Send + 'static,

Nests a service under path.

pub fn frontend(self, params: FrontendParams<S>) -> Self

Declares this server a frontend: it serves HTML to humans.

This is the line between a site and a service, and everything downstream hangs off it — the embedded layout, the icon set, the web manifest, robots.txt, the sitemaps, analytics and browser error monitoring. A server that never calls it needs none of them and boots clean.

pub fn feed(self, feed: Feed) -> Self

Gives this site a feed, served as RSS 2.0, Atom 1.0 and JSON Feed.

Omittable, because most sites publish no stream: a site that never calls this serves no feed documents and emits no autodiscovery links. Requires frontend — calling this without it fails the boot rather than silently serving nothing.

Entries are supplied rather than derived: a blog is a dynamic_page_group, and a dynamic page builds its template data per request, so there is nothing to read at boot. They may be in any order and may exceed MAX_FEED_ENTRIES; the newest survive.

pub fn into_router(self, shutdown: Shutdown) -> Result<Router, WebServerError>

The finished application, without binding a socket.

Exactly the router run serves — pages, the 404, the well-known documents, the cache policy, tracing and the body limit — so driving it with tower::ServiceExt::oneshot tests what ships. Boot validation runs here too: Ok is a server run would have started.

It never runs the drain window or AppShutdown::on_shutdown; triggering shutdown reaches only handlers that listen for it. A .layer() added on top of the result is outside what this library guarantees.

Errors

WebServerError if the frontend cannot be assembled.

pub async fn run(self, shutdown: Shutdown) -> Result<(), WebServerError>

where S: AppShutdown,

Binds, serves, and drains.

Errors

WebServerError if the host is unparseable, the port cannot be bound, the frontend cannot be assembled, or serving fails.