Struct BackgroundServer 

pub struct BackgroundServer { /* private fields */ }

A managed, background HTTP server returned by Server::serve_managed.

The server starts as soon as serve_managed is called. Use this handle to:

• addr — query the current bind address
• rebind — gracefully migrate to a new address
• mechanism — add a route live, no restart
• stop — shut down and await the task

Routes are preserved across rebind

All routes registered before serve_managed, plus any added via mechanism, are automatically carried over when rebind restarts the server.

Ownership

Dropping a BackgroundServer without calling stop leaves the background task running until the Tokio runtime exits.

Example

let mut server = Server::default();
server.mechanism(
    toolkit_zero::socket::server::ServerMechanism::get("/ping")
        .onconnect(|| async { reply!(json => Pong { ok: true }) })
);
let mut bg = server.serve_managed(([127, 0, 0, 1], 8080));
assert_eq!(bg.addr().port(), 8080);

bg.rebind(([127, 0, 0, 1], 9090)).await;
assert_eq!(bg.addr().port(), 9090);

bg.stop().await;

Implementations

impl BackgroundServer

pub fn addr(&self) -> SocketAddr

Returns the address the server is currently bound to.

pub async fn stop(self)

Shuts the server down gracefully and awaits the background task.

In-flight requests complete before the server stops.

pub async fn rebind(&mut self, addr: impl Into<SocketAddr>)

Migrates the server to addr with zero route loss:

1. Sends a graceful shutdown signal to the current instance.
2. Waits for all in-flight requests to complete.
3. Spawns a fresh server task on the new address with the same routes.

After this method returns, addr reflects the new address and the server is accepting connections.

Example

let mut bg = server.serve_managed(([127, 0, 0, 1], 8080));

bg.rebind(([127, 0, 0, 1], 9090)).await;
assert_eq!(bg.addr().port(), 9090);

bg.stop().await;

pub async fn mechanism(&mut self, mech: SocketType) -> &mut Self

Registers a new route on the running server without any restart.

Because routes are stored in an Arc<RwLock<Vec<SocketType>>> shared between this handle and the server’s dispatch loop, writing through the lock makes the new route visible to the next incoming request immediately — no TCP port gap, no in-flight request interruption.

Returns &mut Self for chaining.

Example

use toolkit_zero::socket::server::{Server, ServerMechanism, reply};
use serde::Serialize;

#[derive(Serialize)] struct Pong   { ok:  bool   }
#[derive(Serialize)] struct Status { msg: String }

let mut server = Server::default();
server.mechanism(
    ServerMechanism::get("/ping")
        .onconnect(|| async { reply!(json => Pong { ok: true }) })
);

let mut bg = server.serve_managed(([127, 0, 0, 1], 8080));

bg.mechanism(
    ServerMechanism::get("/status")
        .onconnect(|| async { reply!(json => Status { msg: "enabled".into() }) })
).await;

// /status is now live alongside /ping — no restart.
bg.stop().await;