Struct StatefulSocketBuilder 

pub struct StatefulSocketBuilder<S> { /* private fields */ }

Route builder that carries shared state S with no body or query expectation.

Obtained from ServerMechanism::state. S must be Clone + Send + Sync + 'static. For mutable shared state, wrap it in Arc<Mutex<_>> or Arc<RwLock<_>> before passing it here. Finalise with onconnect / onconnect_sync.

Implementations

impl<S: Clone + Send + Sync + 'static> StatefulSocketBuilder<S>

pub fn json<T: DeserializeOwned + Send>(self) -> StatefulJsonSocketBuilder<T, S>

Adds a JSON body expectation, transitioning to StatefulJsonSocketBuilder.

Alternative ordering to .json::<T>().state(s) — both produce the same route. On each request the incoming JSON body is deserialised into T and a fresh clone of S is prepared; both are handed to the handler together as (state: S, body: T).

Allows .state(s).json::<T>() as an alternative ordering to .json::<T>().state(s).

pub fn query<T: DeserializeOwned + Send>( self, ) -> StatefulQuerySocketBuilder<T, S>

Adds a query parameter expectation, transitioning to StatefulQuerySocketBuilder.

Alternative ordering to .query::<T>().state(s) — both produce the same route. 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 as (state: S, query: T).

Allows .state(s).query::<T>() as an alternative ordering to .query::<T>().state(s).

pub fn encryption<T>( self, key: SerializationKey, ) -> StatefulEncryptedBodyBuilder<T, S>

Adds an encrypted body expectation, transitioning to StatefulEncryptedBodyBuilder.

Alternative ordering to .encryption::<T>(key).state(s) — both produce the same route. On each request the raw body bytes are VEIL-decrypted using key before the handler runs; a wrong key or corrupt body returns 403 Forbidden without invoking the handler. The handler will receive (state: S, body: T) where T is always a trusted, fully-decrypted value.

Allows .state(s).encryption::<T>(key) as an alternative ordering to .encryption::<T>(key).state(s).

pub fn encrypted_query<T>( self, key: SerializationKey, ) -> StatefulEncryptedQueryBuilder<T, S>

Adds an encrypted query expectation, transitioning to StatefulEncryptedQueryBuilder.

Alternative ordering to .encrypted_query::<T>(key).state(s) — both produce the same route. On each request the ?data=<base64url> query parameter is base64-decoded then VEIL-decrypted using key; a missing, malformed, or undecryptable payload returns 403 Forbidden without invoking the handler. The handler will receive (state: S, query: T) where T is always a trusted, fully-decrypted value.

Allows .state(s).encrypted_query::<T>(key) as an alternative ordering to .encrypted_query::<T>(key).state(s).

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

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

Finalises this route with an async handler that receives only the shared state.

On each request a fresh clone of S is injected into the handler. No request body or query parameters are read. 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) -> Result<Re, Rejection> + Clone + Send + Sync + 'static, Re: Reply + Send + 'static,

Finalises this route with a synchronous handler that receives only the shared state.

On each request a fresh clone of S is passed to the handler. If S wraps a mutex or lock, contention across concurrent requests can stall the thread pool — ensure the lock is held only briefly. The closure may block but must complete quickly.

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.