Struct Server

Source

pub struct Server { /* private fields */ }

Expand description

Serves static HTTP content with configurable runtime policies.

You use Server as the main entrypoint to bind an address, map requests to files under a document root, and apply response policies such as CORS, cache hints, and simple rate limiting.

For most production setups, prefer Server::builder so optional settings are explicit and readable.

§Examples

use http_handle::Server;

let server = Server::new("127.0.0.1:8080", ".");
assert_eq!(server.address(), "127.0.0.1:8080");

§Panics

This type does not panic on construction.

Implementations§

Source §

impl Server

Source

pub fn new(address: &str, document_root: &str) -> Self

Creates a server using the minimal required configuration.

Use this constructor when you want a quick default path. For advanced runtime policy, prefer Server::builder.

§Examples

use http_handle::Server;

let server = Server::new("127.0.0.1:8080", ".");
assert_eq!(server.address(), "127.0.0.1:8080");

§Panics

This function does not panic.

Source

pub fn builder() -> ServerBuilder

Returns a fluent builder for optional server policies.

§Examples

use http_handle::Server;

let server = Server::builder()
    .address("127.0.0.1:8080")
    .document_root(".")
    .build()
    .expect("builder should succeed");
assert_eq!(server.address(), "127.0.0.1:8080");

§Panics

This function does not panic.

Source

pub fn start(&self) -> Result<()>

Starts a blocking HTTP/1.1 listener loop.

On Linux, macOS, and Windows, this binds a TcpListener and accepts connections in a thread-per-connection model.

§Examples

use http_handle::Server;

let server = Server::new("127.0.0.1:8080", ".");
let _ = server.start();

§Errors

Returns Err if binding fails or the listener cannot be configured.

§Panics

This function does not intentionally panic.

Source

pub fn start_with_graceful_shutdown( &self, shutdown_timeout: Duration, ) -> Result<()>

Starts the server with OS-signal-aware graceful shutdown.

On macOS/Linux, this responds to SIGINT/SIGTERM via the installed signal handler. On Windows, Ctrl+C triggers equivalent shutdown behavior through the same handler API.

§Examples

use http_handle::Server;
use std::time::Duration;

let server = Server::new("127.0.0.1:8080", ".");
let _ = server.start_with_graceful_shutdown(Duration::from_secs(5));

§Errors

Returns Err when binding or socket configuration fails.

§Panics

This function does not intentionally panic.

Source

pub fn start_with_shutdown_signal( &self, shutdown: Arc<ShutdownSignal>, ) -> Result<()>

Starts the server with caller-managed shutdown coordination.

§Examples

use http_handle::{Server, ShutdownSignal};
use std::sync::Arc;
use std::time::Duration;

let server = Server::new("127.0.0.1:8080", ".");
let signal = Arc::new(ShutdownSignal::new(Duration::from_secs(2)));
let _ = server.start_with_shutdown_signal(signal);

§Errors

Returns Err when binding or listener configuration fails.

§Panics

This function does not intentionally panic.

Source

pub fn start_with_shutdown_signal_and_ready<F>( &self, shutdown: Arc<ShutdownSignal>, on_ready: F, ) -> Result<()>
where F: FnOnce(String),

Starts the server with a shutdown signal and reports the actual bound address.

This is useful when binding to port 0 in tests and callers need the kernel-assigned port before sending requests.

§Arguments

shutdown - The shutdown signal to coordinate graceful termination
on_ready - Callback invoked once with the actual bound ip:port

§Returns

A Result indicating success or an I/O error.

Source

pub fn start_with_thread_pool(&self, thread_pool_size: usize) -> Result<()>

Starts the server with thread pooling for better resource management under load.

This method uses a fixed-size thread pool to handle connections, preventing resource exhaustion under high load by limiting the number of concurrent threads.