Struct ServerHandle 

pub struct ServerHandle { /* private fields */ }

Handle to a running server instance.

This type is experimental and its API may change without notice.

The handle allows the caller to:

• Wait for readiness (via ServerHandle::ready)
• Trigger graceful shutdown (via ServerHandle::shutdown)
• Trigger forced shutdown (via ServerHandle::force_shutdown)
• Query the listening address (via ServerHandle::local_addr)
• Wait for completion (via ServerHandle::wait)

Dropping the handle triggers graceful shutdown — the server stops accepting new connections and drains in-flight requests.

Implementations

impl ServerHandle

pub fn local_addr(&self) -> SocketAddr

Returns the address the server is listening on.

Useful when binding to port 0 to discover the actual port.

pub fn state(&self) -> LifecycleState

Returns the current lifecycle state.

pub async fn ready(&self) -> Result<(), ServerError>

Wait for the server to be ready to accept connections.

This returns once the listener is bound and the accept loop has been polled. After this returns, the server will accept new connections.

If the server fails during startup, this returns an error.

State behavior

• Running: immediate success (already ready)
• Starting: waits for transition to Running or Failed
• Failed: returns startup error
• Created: returns not-started error
• Draining/Stopped: returns not-running error

pub fn shutdown(&self)

Trigger graceful shutdown.

The server will stop accepting new connections and wait for in-flight requests to complete (up to the configured grace period).

Multiple calls are idempotent — only the first call has an effect.

pub async fn force_shutdown( self, deadline: Duration, ) -> Result<ShutdownResult, ServerError>

Trigger forced shutdown with a deadline.

Sends the shutdown signal and waits for the server to stop. If the server does not stop within deadline, the accept task is aborted and the server is marked stopped.

Returns the ShutdownResult indicating how the shutdown completed.

pub async fn wait(self) -> Result<ShutdownResult, ServerError>

Wait for the server to finish.

This consumes the handle. If the server is still running, triggers graceful shutdown first, then waits for all connections to drain. Returns the ShutdownResult indicating how the shutdown completed.

Trait Implementations

impl Debug for ServerHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for ServerHandle

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.