From 67aa8820615f3e5efb487f50ec3dcc0def1ee910 Mon Sep 17 00:00:00 2001 From: David Alsh Date: Sat, 17 Oct 2026 10:12:32 +1100 Subject: [PATCH 1/2] feat(websocket)!: make sender cloneable and add keepalive pings --- crates/uhttp/Cargo.toml | 2 + crates/uhttp/README.md | 10 ++- crates/uhttp/src/lib.rs | 1 + crates/uhttp/src/request.rs | 12 +++ crates/uhttp/src/response.rs | 19 +++++ crates/uhttp/src/router.rs | 5 ++ crates/uhttp/src/websocket.rs | 110 +++++++++++++++++++++++++--- examples/websocket/src/main.rs | 8 +- examples/websocket_chat/src/main.rs | 10 +-- 9 files changed, 153 insertions(+), 24 deletions(-) diff --git a/crates/uhttp/Cargo.toml b/crates/uhttp/Cargo.toml index 198ec35..6420b8f 100644 --- a/crates/uhttp/Cargo.toml +++ b/crates/uhttp/Cargo.toml @@ -27,6 +27,8 @@ tokio = { workspace = true, features = [ "fs", "net", "macros", + "sync", + "time", ] } tokio-util = { workspace = true, features = ["io", "io-util", "futures-util"] } diff --git a/crates/uhttp/README.md b/crates/uhttp/README.md index b32a6ad..c0b10ee 100644 --- a/crates/uhttp/README.md +++ b/crates/uhttp/README.md @@ -273,16 +273,22 @@ use uhttp::websocket::Websocket; async fn main() -> anyhow::Result<()> { Server::builder() .handler(|req, res| async move { - Websocket::upgrade(req, res, |mut socket| async move { + Websocket::upgrade(req, res, |socket_sender, mut socket_receiver| async move { tokio::task::spawn(async move { loop { - if socket.send("Hello").await.is_err() { + if socket_sender.send_raw("Hello").await.is_err() { break; }; tokio::time::sleep(Duration::from_millis(1000)).await; } }); + tokio::task::spawn(async move { + while let Ok(Some(msg)) = socket_receiver.recv_raw().await { + println!("GOT: {:?}", msg); + } + }); + Ok(()) }) }) diff --git a/crates/uhttp/src/lib.rs b/crates/uhttp/src/lib.rs index d848754..2976b19 100644 --- a/crates/uhttp/src/lib.rs +++ b/crates/uhttp/src/lib.rs @@ -18,6 +18,7 @@ mod types; #[cfg(feature = "websocket")] mod websocket; +pub use http::Method; pub use http::StatusCode; pub use tokio_util::sync::CancellationToken; diff --git a/crates/uhttp/src/request.rs b/crates/uhttp/src/request.rs index ca01b33..7bfe81a 100644 --- a/crates/uhttp/src/request.rs +++ b/crates/uhttp/src/request.rs @@ -35,6 +35,15 @@ pub struct Request { pub body: Pin>, pub params: HashMap, + + /// The route *pattern* this request matched, e.g. `/users/:id` — never the + /// concrete path. + /// + /// Populated by the router after matching. Telemetry should label spans and + /// metrics with this rather than `uri.path()`, since the concrete path embeds + /// ids and would create unbounded cardinality. `None` means nothing matched + /// (the 404 path). + pub route: Option, } impl Default for Request { @@ -47,6 +56,7 @@ impl Default for Request { extensions: Default::default(), body: Box::pin(tokio::io::empty()), params: Default::default(), + route: None, } } } @@ -87,6 +97,8 @@ impl Request { extensions: parts.extensions, params: HashMap::new(), body: Box::pin(body), + // Set by the router once a route matches; see the field docs. + route: None, } } diff --git a/crates/uhttp/src/response.rs b/crates/uhttp/src/response.rs index 4098321..c59947d 100644 --- a/crates/uhttp/src/response.rs +++ b/crates/uhttp/src/response.rs @@ -6,6 +6,8 @@ use http::HeaderName; use http::HeaderValue; use http::StatusCode; use http::Version; +#[cfg(feature = "json")] +use serde::Serialize; use super::types::HyperResponseBuilder; use crate::ResponseBody; @@ -92,4 +94,21 @@ impl Response { }; Ok(response?) } + + /// Build a response with an empty body. + pub fn empty(self) -> crate::Result { + self.body(vec![]) + } + + /// Build a JSON response, setting the `Content-Type` header to + /// `application/json`. + #[cfg(feature = "json")] + pub fn json( + self, + json: impl Serialize, + ) -> crate::Result { + self + .header("Content-Type", "application/json") + .body(serde_json::to_vec(&json)?) + } } diff --git a/crates/uhttp/src/router.rs b/crates/uhttp/src/router.rs index 236c75e..bb5c08c 100644 --- a/crates/uhttp/src/router.rs +++ b/crates/uhttp/src/router.rs @@ -296,6 +296,11 @@ impl Router { .await; }; + // `pattern()` gives the route as registered (with `:param` + // placeholders) rather than the concrete path, which is what keeps + // telemetry cardinality bounded. + req.route = Some(params.pattern()); + for (key, value) in params.params() { req.params.insert( key.to_string(), diff --git a/crates/uhttp/src/websocket.rs b/crates/uhttp/src/websocket.rs index dc32d4d..ac944dd 100644 --- a/crates/uhttp/src/websocket.rs +++ b/crates/uhttp/src/websocket.rs @@ -1,4 +1,7 @@ use std::future::Future; +use std::sync::Arc; +use std::sync::Weak; +use std::time::Duration; use anyhow::anyhow; use futures::SinkExt; @@ -9,6 +12,11 @@ use http::header; use hyper::upgrade::OnUpgrade; use hyper::upgrade::Upgraded; use hyper_util::rt::TokioIo; +#[cfg(feature = "json")] +use serde::Serialize; +#[cfg(feature = "json")] +use serde::de::DeserializeOwned; +use tokio::sync::Mutex; use tokio_tungstenite::WebSocketStream; pub use tokio_tungstenite::tungstenite::Message; use tokio_tungstenite::tungstenite::handshake::derive_accept_key; @@ -16,6 +24,12 @@ pub use tokio_tungstenite::tungstenite::protocol::CloseFrame; use tokio_tungstenite::tungstenite::protocol::Role; type WebsocketIo = WebSocketStream>; +type WebsocketSink = SplitSink; + +/// How often to ping the peer. Browsers cannot send pings themselves, so the +/// server has to keep the connection warm or intermediate proxies (which +/// commonly idle out at 60s) will drop it. +const PING_INTERVAL: Duration = Duration::from_secs(30); pub struct Websocket { stream: WebsocketIo, @@ -28,7 +42,7 @@ impl Websocket { callback: F, ) -> crate::Result where - F: 'static + Send + FnOnce(Websocket) -> Fut, + F: 'static + Send + FnOnce(WebsocketSender, WebsocketReceiver) -> Fut, Fut: 'static + Send + Future>, { let version = req.headers.get(header::SEC_WEBSOCKET_VERSION); @@ -57,7 +71,11 @@ impl Websocket { let stream = WebSocketStream::from_raw_socket(TokioIo::new(upgraded), Role::Server, None).await; - callback(Websocket { stream }).await.ok(); + let (sender, receiver) = Websocket { stream }.split(); + + tokio::spawn(keepalive(Arc::downgrade(&sender.0))); + + let _ = callback(sender, receiver).await; }); res @@ -93,34 +111,85 @@ impl Websocket { pub fn split(self) -> (WebsocketSender, WebsocketReceiver) { let (sender, receiver) = self.stream.split(); - (WebsocketSender(sender), WebsocketReceiver(receiver)) + ( + WebsocketSender(Arc::new(Mutex::new(sender))), + WebsocketReceiver(receiver), + ) } pub fn reunite( sender: WebsocketSender, receiver: WebsocketReceiver, ) -> crate::Result { - let stream = sender.0.reunite(receiver.0)?; + let sender = Arc::try_unwrap(sender.0) + .map_err(|_| anyhow!("websocket sender is still cloned elsewhere"))? + .into_inner(); + + let stream = sender.reunite(receiver.0)?; Ok(Self { stream }) } } -pub struct WebsocketSender(SplitSink); +/// Pings the peer on an interval until the socket errors or every +/// [`WebsocketSender`] has been dropped. Holds a [`Weak`] so it neither keeps the +/// socket alive on its own nor blocks [`Websocket::reunite`]. +async fn keepalive(sink: Weak>) { + let mut interval = tokio::time::interval(PING_INTERVAL); + interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + interval.tick().await; + + loop { + interval.tick().await; + + let Some(sink) = sink.upgrade() else { + return; + }; + + if sink + .lock() + .await + .send(Message::Ping(Default::default())) + .await + .is_err() + { + return; + } + } +} + +/// A cloneable handle for sending messages on a websocket. +/// +/// Cloning is cheap and every clone shares the same underlying sink, so the +/// connection can be driven from several tasks at once (e.g. one task relaying +/// messages received from a broadcast channel while another handles pongs). +#[derive(Clone)] +pub struct WebsocketSender(Arc>); impl WebsocketSender { - pub async fn send( - &mut self, + /// Serialize `message` as JSON and send it as a text frame. + #[cfg(feature = "json")] + pub async fn send( + &self, + message: S, + ) -> crate::Result<()> { + let json = serde_json::to_string(&message)?; + self.send_raw(Message::text(json)).await + } + + /// Send a raw websocket message. + pub async fn send_raw( + &self, message: impl Into, ) -> crate::Result<()> { - self.0.send(message.into()).await?; + self.0.lock().await.send(message.into()).await?; Ok(()) } pub async fn close( - &mut self, + &self, frame: Option, ) -> crate::Result<()> { - self.0.send(Message::Close(frame)).await?; + self.0.lock().await.send(Message::Close(frame)).await?; Ok(()) } } @@ -128,7 +197,26 @@ impl WebsocketSender { pub struct WebsocketReceiver(SplitStream); impl WebsocketReceiver { - pub async fn recv(&mut self) -> crate::Result> { + /// Receive the next message, deserializing JSON text/binary frames. + /// + /// Ping, Pong and Frame messages are skipped. A close frame (or the socket + /// ending) yields `Ok(None)`. + #[cfg(feature = "json")] + pub async fn recv(&mut self) -> crate::Result> { + while let Some(message) = self.0.next().await { + let payload = match message? { + Message::Text(text) => serde_json::from_str(&text)?, + Message::Binary(bytes) => serde_json::from_slice(&bytes)?, + Message::Close(_) => return Ok(None), + Message::Ping(_) | Message::Pong(_) | Message::Frame(_) => continue, + }; + return Ok(Some(payload)); + } + Ok(None) + } + + /// Receive the next raw websocket message. + pub async fn recv_raw(&mut self) -> crate::Result> { match self.0.next().await { Some(message) => Ok(Some(message?)), None => Ok(None), diff --git a/examples/websocket/src/main.rs b/examples/websocket/src/main.rs index b273997..e7d7d58 100644 --- a/examples/websocket/src/main.rs +++ b/examples/websocket/src/main.rs @@ -11,12 +11,10 @@ use uhttp::Websocket; async fn main() -> anyhow::Result<()> { Server::builder() .handler(|req, res| async move { - Websocket::upgrade(req, res, |socket| async move { - let (mut socket_sender, mut socket_receiver) = socket.split(); - + Websocket::upgrade(req, res, |socket_sender, mut socket_receiver| async move { tokio::task::spawn(async move { loop { - if socket_sender.send("Hello").await.is_err() { + if socket_sender.send_raw("Hello").await.is_err() { break; }; tokio::time::sleep(Duration::from_millis(1000)).await; @@ -24,7 +22,7 @@ async fn main() -> anyhow::Result<()> { }); tokio::task::spawn(async move { - while let Ok(Some(msg)) = socket_receiver.recv().await { + while let Ok(Some(msg)) = socket_receiver.recv_raw().await { println!("GOT: {:?}", msg); } }); diff --git a/examples/websocket_chat/src/main.rs b/examples/websocket_chat/src/main.rs index e727b3b..8f57f9e 100644 --- a/examples/websocket_chat/src/main.rs +++ b/examples/websocket_chat/src/main.rs @@ -32,9 +32,7 @@ async fn main() -> anyhow::Result<()> { app.any( "/api/ws", move |req, res, Context { chat_service }: Context| async move { - Websocket::upgrade(req, res, |socket| async move { - let (mut socket_sender, mut socket_receiver) = socket.split(); - + Websocket::upgrade(req, res, |socket_sender, mut socket_receiver| async move { // Send action tokio::task::spawn({ let chat_service = Arc::clone(&chat_service); @@ -47,7 +45,7 @@ async fn main() -> anyhow::Result<()> { return; }; - if socket_sender.send(msg).await.is_err() { + if socket_sender.send_raw(msg).await.is_err() { return; }; @@ -62,7 +60,7 @@ async fn main() -> anyhow::Result<()> { break; }; - if socket_sender.send(msg).await.is_err() { + if socket_sender.send_raw(msg).await.is_err() { break; }; } @@ -73,7 +71,7 @@ async fn main() -> anyhow::Result<()> { tokio::task::spawn({ let chat_service = Arc::clone(&chat_service); async move { - while let Some(msg) = socket_receiver.recv().await? { + while let Some(msg) = socket_receiver.recv_raw().await? { let uhttp::Message::Text(msg) = msg else { continue; }; From c0e11d9fcf1c90655a45e52b893065c3dfbcb5a6 Mon Sep 17 00:00:00 2001 From: David Alsh Date: Sat, 17 Oct 2026 10:19:07 +1100 Subject: [PATCH 2/2] feat(router): gate request params and route behind router feature --- crates/uhttp/src/request.rs | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/crates/uhttp/src/request.rs b/crates/uhttp/src/request.rs index 7bfe81a..f356e93 100644 --- a/crates/uhttp/src/request.rs +++ b/crates/uhttp/src/request.rs @@ -1,3 +1,4 @@ +#[cfg(feature = "router")] use std::collections::HashMap; use std::pin::Pin; @@ -34,6 +35,7 @@ pub struct Request { pub body: Pin>, + #[cfg(feature = "router")] pub params: HashMap, /// The route *pattern* this request matched, e.g. `/users/:id` — never the @@ -43,6 +45,7 @@ pub struct Request { /// metrics with this rather than `uri.path()`, since the concrete path embeds /// ids and would create unbounded cardinality. `None` means nothing matched /// (the 404 path). + #[cfg(feature = "router")] pub route: Option, } @@ -55,7 +58,9 @@ impl Default for Request { headers: Default::default(), extensions: Default::default(), body: Box::pin(tokio::io::empty()), + #[cfg(feature = "router")] params: Default::default(), + #[cfg(feature = "router")] route: None, } } @@ -66,15 +71,19 @@ impl std::fmt::Debug for Request { &self, f: &mut std::fmt::Formatter<'_>, ) -> std::fmt::Result { - f.debug_struct("Request") + let mut debug = f.debug_struct("Request"); + debug .field("method", &self.method) .field("uri", &self.uri) .field("version", &self.version) .field("headers", &self.headers) .field("extensions", &self.extensions) - .field("body", &"".to_string()) + .field("body", &"".to_string()); + #[cfg(feature = "router")] + debug .field("params", &self.params) - .finish() + .field("route", &self.route); + debug.finish() } } @@ -95,9 +104,11 @@ impl Request { version: parts.version, headers: parts.headers, extensions: parts.extensions, + #[cfg(feature = "router")] params: HashMap::new(), body: Box::pin(body), // Set by the router once a route matches; see the field docs. + #[cfg(feature = "router")] route: None, } }