Struct StatefulQuerySocketBuilder 

pub struct StatefulQuerySocketBuilder<T, S> { /* private fields */ }

Route builder that carries shared state S and expects URL query parameters of type T.

Obtained from QuerySocketBuilder::state. S must be Clone + Send + Sync + 'static. T must implement serde::de::DeserializeOwned. Finalise with onconnect / onconnect_sync.

Implementations

impl<T: DeserializeOwned + Send + 'static, S: Clone + Send + Sync + 'static> StatefulQuerySocketBuilder<T, S>

pub fn onconnect<F, Fut, Re>(self, handler: F) -> SocketType

where F: Fn(S, T) -> Fut + Clone + Send + Sync + 'static, Fut: Future<Output = Result<Re, Rejection>> + Send, Re: Reply + Send,

Finalises this route with an async handler that receives (state: S, query: T).

On each request the URL query string is deserialised into T and a fresh clone of S is prepared — both are handed to the handler together. A missing or malformed query string is rejected before the handler is ever invoked.

The handler must return Result<impl Reply, Rejection>. Returns a SocketType ready to be passed to Server::mechanism.

pub unsafe fn onconnect_sync<F, Re>(self, handler: F) -> SocketType

where F: Fn(S, T) -> Result<Re, Rejection> + Clone + Send + Sync + 'static, Re: Reply + Send + 'static,

Finalises this route with a synchronous handler that receives (state: S, query: T).

The query string is decoded into T and a clone of S is prepared before the blocking handler is dispatched. If S wraps a lock, keep it held only briefly. See ServerMechanism::onconnect_sync for the full thread-pool safety notes.

Returns a SocketType ready to be passed to Server::mechanism.

Safety

Every incoming request spawns an independent task on Tokio’s blocking thread pool. The pool caps the number of live OS threads (default 512), but the queue of waiting tasks is unbounded — under a traffic surge, tasks accumulate without limit, consuming unbounded memory and causing severe latency spikes or OOM crashes before any queued task gets a chance to run. When the handler acquires a lock on S (e.g. Arc<Mutex<_>>), concurrent blocking tasks contending on the same lock can stall indefinitely, causing the thread pool queue to grow without bound and compounding the exhaustion risk. Additionally, any panic inside the handler is silently converted into a Rejection, masking runtime errors. Callers must ensure the handler completes quickly, that lock contention on S cannot produce indefinite stalls, and that adequate backpressure or rate limiting is applied externally.