Struct TcpServer 

pub struct TcpServer { /* private fields */ }

TCP server with asupersync integration.

This server manages the lifecycle of connections and requests using asupersync’s structured concurrency primitives. Each connection runs in its own region, and each request gets its own task with a budget.

Implementations

impl TcpServer

pub fn new(config: ServerConfig) -> Self

Creates a new TCP server with the given configuration.

pub fn config(&self) -> &ServerConfig

Returns the server configuration.

pub fn current_connections(&self) -> u64

Returns the current number of active connections.

pub fn metrics(&self) -> ServerMetrics

Returns a snapshot of the server’s connection pool metrics.

pub fn is_draining(&self) -> bool

Returns true if the server is draining (shutting down gracefully).

pub fn start_drain(&self)

Starts the drain process for graceful shutdown.

This sets the draining flag, which causes the server to:

• Stop accepting new connections
• Return 503 to new connection attempts
• Allow in-flight requests to complete

pub async fn wait_for_drain( &self, timeout: Duration, poll_interval: Option<Duration>, ) -> bool

Waits for all in-flight connections to drain, with a timeout.

Returns true if all connections drained successfully, false if the timeout was reached with connections still active.

Arguments

• timeout - Maximum time to wait for connections to drain
• poll_interval - How often to check connection count (default 10ms)

pub async fn drain(&self) -> u64

Initiates graceful shutdown and waits for connections to drain.

This is a convenience method that combines start_drain() and wait_for_drain() using the configured drain timeout.

Returns the number of connections that were forcefully closed (0 if all drained within the timeout).

pub fn shutdown_controller(&self) -> &Arc<ShutdownController>

Returns a reference to the server’s shutdown controller.

This can be used to coordinate shutdown from external code, such as signal handlers or health check endpoints.

pub fn subscribe_shutdown(&self) -> ShutdownReceiver

Returns a receiver for shutdown notifications.

Use this to receive shutdown signals in other parts of your application. Multiple receivers can be created and they will all be notified.

pub fn shutdown(&self)

Initiates server shutdown.

This triggers the shutdown process:

1. Sets the draining flag to stop accepting new connections
2. Notifies all shutdown receivers
3. The server’s accept loop will exit and drain connections

This method is safe to call multiple times - subsequent calls are no-ops.

pub fn is_shutting_down(&self) -> bool

Checks if shutdown has been initiated.

pub async fn serve_with_shutdown<H, Fut>( &self, cx: &Cx, shutdown: ShutdownReceiver, handler: H, ) -> Result<GracefulOutcome<()>, ServerError>

where H: Fn(RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Runs the server with graceful shutdown support.

The server will run until either:

• The provided shutdown receiver signals shutdown
• The server Cx is cancelled
• An unrecoverable error occurs

When shutdown is signaled, the server will:

1. Stop accepting new connections
2. Wait for existing connections to complete (up to drain_timeout)
3. Return gracefully

Example

use asupersync::signal::ShutdownController;
use fastapi_http::{TcpServer, ServerConfig};

let controller = ShutdownController::new();
let server = TcpServer::new(ServerConfig::new("127.0.0.1:8080"));

// Get a shutdown receiver
let shutdown = controller.subscribe();

// In another task, you can trigger shutdown:
// controller.shutdown();

server.serve_with_shutdown(&cx, shutdown, handler).await?;

pub async fn serve<H, Fut>( &self, cx: &Cx, handler: H, ) -> Result<(), ServerError>

where H: Fn(RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Runs the server, accepting connections and handling requests.

This method will run until the server Cx is cancelled or an unrecoverable error occurs.

Arguments

• cx - The capability context for the server region
• handler - The request handler function

Errors

Returns an error if binding fails or an unrecoverable IO error occurs.

pub async fn serve_on<H, Fut>( &self, cx: &Cx, listener: TcpListener, handler: H, ) -> Result<(), ServerError>

where H: Fn(RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Runs the server on a specific listener.

This is useful when you already have a bound listener.

pub async fn serve_handler( &self, cx: &Cx, handler: Arc<dyn Handler>, ) -> Result<(), ServerError>

Runs the server with a Handler trait object.

This is the recommended way to serve an application that implements the Handler trait (like App).

Example

use fastapi_http::TcpServer;
use fastapi_core::{App, Handler};
use std::sync::Arc;

let app = App::builder()
    .get("/", handler_fn)
    .build();

let server = TcpServer::new(ServerConfig::new("127.0.0.1:8080"));
let cx = Cx::for_testing();
server.serve_handler(&cx, Arc::new(app)).await?;

pub async fn serve_on_handler( &self, cx: &Cx, listener: TcpListener, handler: Arc<dyn Handler>, ) -> Result<(), ServerError>

Runs the server on a specific listener with a Handler trait object.

pub async fn serve_concurrent<H, Fut>( &self, cx: &Cx, scope: &Scope<'_>, state: &mut RuntimeState, handler: H, ) -> Result<(), ServerError>

where H: Fn(RequestContext, &mut Request) -> Fut + Send + Sync + 'static, Fut: Future<Output = Response> + Send + 'static,

Serves HTTP requests with concurrent connection handling using asupersync Scope.

This method uses Scope::spawn_registered for proper structured concurrency, ensuring all spawned connection tasks are tracked and can be properly drained during shutdown.

Arguments

• cx - The asupersync context for cancellation and tracing
• scope - A scope for spawning connection tasks
• state - Runtime state for task registration
• handler - The request handler

Trait Implementations

impl Debug for TcpServer

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

Formats the value using the given formatter.

impl Default for TcpServer

fn default() -> Self

Returns the “default value” for a type.