Skip to main content

redis_tower_core/
frame_service.rs

1//! A `Service<Frame, Response=Frame>` adapter for `RedisConnection`.
2//!
3//! Enables Frame-level Tower middleware (caching, logging, metrics)
4//! that operates on raw RESP frames rather than typed commands.
5
6use std::future::Future;
7use std::pin::Pin;
8use std::task::{Context, Poll};
9
10use futures::Sink;
11use futures::SinkExt;
12use tokio::sync::oneshot;
13use tokio_stream::StreamExt;
14use tokio_util::codec::Framed;
15
16use crate::error::RedisError;
17use crate::stream::RedisStream;
18use redis_tower_protocol::{Frame, RespCodec};
19
20/// A Tower `Service` that sends and receives raw RESP frames.
21///
22/// This is the lowest-level service primitive. It sends a `Frame` on the
23/// wire and returns the response `Frame`. No command parsing, no type
24/// safety -- just raw frame I/O.
25///
26/// Use this as the inner service for Frame-level middleware (caching,
27/// logging, metrics), then wrap with `CommandAdapter` to restore
28/// typed command dispatch.
29///
30/// Cancelling an in-flight call closes the connection. Once a request may
31/// have reached Redis, reusing its transport could let the next call consume
32/// the cancelled request's late response. A subsequent `poll_ready` therefore
33/// returns [`RedisError::ConnectionClosed`].
34///
35/// # Example
36///
37/// ```no_run
38/// use futures::future::poll_fn;
39/// use redis_tower_core::FrameService;
40/// use redis_tower_protocol::helpers::{array, bulk};
41/// use tower_service::Service;
42///
43/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
44/// let mut svc = FrameService::connect("127.0.0.1:6379").await?;
45/// poll_fn(|cx| svc.poll_ready(cx)).await?;
46/// let response = svc.call(array(vec![bulk("PING")])).await?;
47/// # let _ = response;
48/// # Ok(())
49/// # }
50/// ```
51pub struct FrameService {
52    /// The framed transport. `None` while a `Service::call` future is in flight.
53    framed: Option<Framed<RedisStream, RespCodec>>,
54    /// Optional sender for RESP3 push messages.
55    push_tx: Option<tokio::sync::mpsc::UnboundedSender<Frame>>,
56    /// Channel to reclaim the framed transport after a `Service::call` completes.
57    inflight: Option<oneshot::Receiver<Framed<RedisStream, RespCodec>>>,
58}
59
60impl FrameService {
61    /// Connect to a Redis server and create a FrameService.
62    pub async fn connect(addr: &str) -> Result<Self, RedisError> {
63        let conn = crate::connection::RedisConnection::connect(addr).await?;
64        Self::from_connection(conn)
65    }
66
67    /// Create from an existing `RedisConnection`, consuming it.
68    pub fn from_connection(conn: crate::connection::RedisConnection) -> Result<Self, RedisError> {
69        let framed = conn.into_framed()?;
70        Ok(Self {
71            framed: Some(framed),
72            push_tx: None,
73            inflight: None,
74        })
75    }
76
77    /// Subscribe to RESP3 push messages.
78    ///
79    /// Returns a receiver for out-of-band push frames (e.g., invalidation
80    /// messages from CLIENT TRACKING). Push frames received during normal
81    /// command execution are automatically routed to this channel.
82    pub fn subscribe_pushes(&mut self) -> tokio::sync::mpsc::UnboundedReceiver<Frame> {
83        let (tx, rx) = tokio::sync::mpsc::unbounded_channel();
84        self.push_tx = Some(tx);
85        rx
86    }
87}
88
89/// Owns the framed transport while a `Service::call` future is in flight.
90///
91/// The transport is returned through `return_tx` only after a complete
92/// response frame has been read. Dropping the future, or encountering a
93/// transport/protocol error before that boundary, drops both fields and closes
94/// the connection rather than leaving a late response for the next request.
95struct FrameGuardFs {
96    framed: Option<Framed<RedisStream, RespCodec>>,
97    return_tx: Option<oneshot::Sender<Framed<RedisStream, RespCodec>>>,
98}
99
100impl tower_service::Service<Frame> for FrameService {
101    type Response = Frame;
102    type Error = RedisError;
103    type Future = Pin<Box<dyn Future<Output = Result<Frame, RedisError>> + Send>>;
104
105    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
106        // Reclaim the transport from an in-flight future if needed.
107        if self.framed.is_none() {
108            if let Some(ref mut rx) = self.inflight {
109                match Pin::new(rx).poll(cx) {
110                    Poll::Ready(Ok(framed)) => {
111                        self.framed = Some(framed);
112                        self.inflight = None;
113                    }
114                    Poll::Ready(Err(_)) => {
115                        self.inflight = None;
116                        return Poll::Ready(Err(RedisError::ConnectionClosed));
117                    }
118                    Poll::Pending => return Poll::Pending,
119                }
120            } else {
121                return Poll::Ready(Err(RedisError::ConnectionClosed));
122            }
123        }
124
125        let framed = self.framed.as_mut().unwrap();
126        Pin::new(framed).poll_ready(cx).map_err(RedisError::from)
127    }
128
129    fn call(&mut self, request: Frame) -> Self::Future {
130        let mut framed = self
131            .framed
132            .take()
133            .expect("call() invoked without successful poll_ready()");
134        let push_tx = self.push_tx.clone();
135
136        if let Err(e) = Pin::new(&mut framed).start_send(request) {
137            // A sink error leaves the connection state uncertain. Quarantine
138            // it rather than allowing a later call to reuse the transport.
139            return Box::pin(async move { Err(RedisError::from(e)) });
140        }
141
142        let (return_tx, return_rx) = oneshot::channel();
143        self.inflight = Some(return_rx);
144
145        // Keep the transport owned by the call future. Cancellation or an I/O
146        // error before a complete response drops it; a complete response
147        // restores protocol alignment regardless of the frame's contents.
148        let mut guard = FrameGuardFs {
149            framed: Some(framed),
150            return_tx: Some(return_tx),
151        };
152
153        Box::pin(async move {
154            let framed = guard.framed.as_mut().unwrap();
155
156            framed.flush().await.map_err(RedisError::from)?;
157
158            // Read response, routing push frames.
159            let response = loop {
160                let frame = framed
161                    .next()
162                    .await
163                    .ok_or(RedisError::ConnectionClosed)?
164                    .map_err(RedisError::from)?;
165
166                if let Frame::Push(_) = &frame {
167                    if let Some(ref tx) = push_tx {
168                        let _ = tx.send(frame);
169                    }
170                    continue;
171                }
172
173                break frame;
174            };
175
176            // Explicitly return the transport on success (disarms the guard).
177            let _ = guard
178                .return_tx
179                .take()
180                .unwrap()
181                .send(guard.framed.take().unwrap());
182            Ok(response)
183        })
184    }
185}
186
187#[cfg(test)]
188mod tests {
189    use super::*;
190    use std::time::Duration;
191    use tower_service::Service;
192
193    async fn stream_pair() -> (RedisStream, RedisStream) {
194        #[cfg(unix)]
195        {
196            let (client, server) = tokio::net::UnixStream::pair().unwrap();
197            (RedisStream::Unix(client), RedisStream::Unix(server))
198        }
199        #[cfg(not(unix))]
200        {
201            let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
202            let addr = listener.local_addr().unwrap();
203            let client = tokio::net::TcpStream::connect(addr).await.unwrap();
204            let (server, _) = listener.accept().await.unwrap();
205            (RedisStream::Tcp(client), RedisStream::Tcp(server))
206        }
207    }
208
209    #[tokio::test]
210    async fn timeout_after_wire_quarantines_frame_transport() {
211        let (client, server) = stream_pair().await;
212        let (wire_tx, mut wire_rx) = oneshot::channel();
213        let (release_tx, release_rx) = oneshot::channel();
214        let (late_attempt_tx, late_attempt_rx) = oneshot::channel();
215
216        let server_task = tokio::spawn(async move {
217            let mut framed = Framed::new(server, RespCodec::new());
218            framed
219                .next()
220                .await
221                .expect("client closed before sending its frame")
222                .expect("client sent an invalid frame");
223            wire_tx.send(()).unwrap();
224
225            release_rx.await.unwrap();
226            let late_result = framed.send(Frame::SimpleString(b"LATE"[..].into())).await;
227            late_attempt_tx.send(()).unwrap();
228
229            if late_result.is_ok() {
230                match tokio::time::timeout(Duration::from_secs(1), framed.next()).await {
231                    Ok(None) | Ok(Some(Err(_))) => {}
232                    Ok(Some(Ok(frame))) => panic!("timed-out socket was reused: {frame:?}"),
233                    Err(_) => panic!("timed-out socket remained open"),
234                }
235            }
236        });
237
238        let conn = crate::connection::RedisConnection::from_stream(client);
239        let mut service = FrameService::from_connection(conn).unwrap();
240        futures::future::poll_fn(|cx| Service::<Frame>::poll_ready(&mut service, cx))
241            .await
242            .unwrap();
243        let mut call =
244            Service::<Frame>::call(&mut service, Frame::SimpleString(b"REQUEST"[..].into()));
245
246        // First drive the call until the server has decoded the request. The
247        // response remains withheld, so the timeout deterministically owns
248        // cancellation after the write has reached the peer.
249        tokio::select! {
250            result = &mut call => panic!("call completed before timeout: {result:?}"),
251            observed = &mut wire_rx => observed.unwrap(),
252        }
253        let timeout_result = tokio::time::timeout(Duration::from_millis(10), call).await;
254        assert!(
255            timeout_result.is_err(),
256            "withheld response did not time out"
257        );
258
259        release_tx.send(()).unwrap();
260        late_attempt_rx.await.unwrap();
261
262        let mut cx = Context::from_waker(futures::task::noop_waker_ref());
263        let readiness = Service::<Frame>::poll_ready(&mut service, &mut cx);
264        let is_closed = matches!(readiness, Poll::Ready(Err(RedisError::ConnectionClosed)));
265        drop(service);
266        server_task.await.unwrap();
267
268        assert!(
269            is_closed,
270            "timed-out connection was reusable: {readiness:?}"
271        );
272    }
273}