Skip to main content

turnloop_redis/
lib.rs

1#![deny(unsafe_op_in_unsafe_fn)]
2//!
3//! # Getting started on turnloop
4//! Enable the `turnloop` feature for the `asynchronous` module. The embedding
5//! host owns `LocalExecutor` and calls `turn`; adapters await its streams and
6//! deadline futures. See the crate README and turnloop-io for ownership, streaming
7//! and cancellation examples. Default features retain the sans-I/O API.
8
9//! Sans-I/O Redis connection. The host drains `output`, acknowledges writes with
10//! `consume_output`, supplies bytes/time, and polls events. Never reads a clock.
11//! Tokens are unique among outstanding commands. A timeout leaves a wire-order
12//! tombstone until its reply arrives, preventing later replies being misassigned.
13pub mod resp;
14pub mod routing;
15use resp::{Limits, Value, encode_command};
16use std::{
17    collections::VecDeque,
18    time::{Duration, Instant},
19};
20
21#[derive(Debug, Clone)]
22pub struct Config {
23    pub username: Option<String>,
24    pub password: Option<String>,
25    pub database: u32,
26    pub client_name: Option<String>,
27    pub tls: bool,
28    pub prefer_resp3: bool,
29    pub offline_queue: bool,
30    pub auto_resubscribe: bool,
31    pub auto_resend_unfulfilled: bool,
32    pub max_retries_per_request: Option<u32>,
33    pub connect_timeout: Duration,
34    pub limits: Limits,
35}
36impl Default for Config {
37    fn default() -> Self {
38        Self {
39            username: None,
40            password: None,
41            database: 0,
42            client_name: None,
43            tls: false,
44            prefer_resp3: true,
45            offline_queue: true,
46            auto_resubscribe: true,
47            auto_resend_unfulfilled: true,
48            max_retries_per_request: Some(20),
49            connect_timeout: Duration::from_secs(10),
50            limits: Limits::default(),
51        }
52    }
53}
54#[derive(Debug, Clone, PartialEq, Eq)]
55pub struct Error {
56    pub name: &'static str,
57    pub message: String,
58}
59impl Error {
60    fn new(message: &str) -> Self {
61        Self {
62            name: "Error",
63            message: message.into(),
64        }
65    }
66    fn reply(bytes: Vec<u8>) -> Self {
67        Self {
68            name: "ReplyError",
69            message: String::from_utf8_lossy(&bytes).into_owned(),
70        }
71    }
72}
73impl std::fmt::Display for Error {
74    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75        write!(f, "{}: {}", self.name, self.message)
76    }
77}
78impl std::error::Error for Error {}
79#[derive(Debug, Clone, Copy, PartialEq, Eq)]
80pub enum State {
81    Disconnected,
82    Connecting,
83    Tls,
84    Handshake,
85    Ready,
86    RetryDecision,
87    WaitingRetry,
88    Closed,
89}
90#[derive(Debug, PartialEq)]
91pub enum Event {
92    Connect,
93    UpgradeTls,
94    Ready {
95        resp3: bool,
96    },
97    Reply {
98        token: u64,
99        result: Result<Value, Error>,
100    },
101    Message {
102        pattern: Option<Vec<u8>>,
103        channel: Vec<u8>,
104        payload: Vec<u8>,
105    },
106    Push(Value),
107    /// Evaluate retryStrategy(attempt) in the host, then call `retry`.
108    Retry {
109        attempt: u32,
110    },
111    Error(Error),
112    CloseTransport,
113    Closed,
114}
115#[derive(Debug, Clone, Copy, PartialEq, Eq)]
116enum Kind {
117    Normal,
118    Subscribe,
119    Psubscribe,
120    Unsubscribe,
121    Punsubscribe,
122    Quit,
123}
124impl Kind {
125    fn of(name: &[u8]) -> Self {
126        if name.eq_ignore_ascii_case(b"SUBSCRIBE") {
127            Self::Subscribe
128        } else if name.eq_ignore_ascii_case(b"PSUBSCRIBE") {
129            Self::Psubscribe
130        } else if name.eq_ignore_ascii_case(b"UNSUBSCRIBE") {
131            Self::Unsubscribe
132        } else if name.eq_ignore_ascii_case(b"PUNSUBSCRIBE") {
133            Self::Punsubscribe
134        } else if name.eq_ignore_ascii_case(b"QUIT") {
135            Self::Quit
136        } else {
137            Self::Normal
138        }
139    }
140    fn subscription(self) -> bool {
141        matches!(
142            self,
143            Self::Subscribe | Self::Psubscribe | Self::Unsubscribe | Self::Punsubscribe
144        )
145    }
146}
147struct Pending {
148    token: Option<u64>,
149    wire: Vec<u8>,
150    deadline: Option<Instant>,
151    kind: Kind,
152    acks: usize,
153}
154#[derive(Clone, Copy)]
155enum Handshake {
156    Hello,
157    Auth,
158    Select,
159    Name,
160    Restore,
161}
162pub struct Connection {
163    config: Config,
164    state: State,
165    resp3: bool,
166    handshake: Handshake,
167    tx: Vec<u8>,
168    tx_pos: usize,
169    rx: Vec<u8>,
170    events: VecDeque<Event>,
171    pending: VecDeque<Pending>,
172    offline: VecDeque<Pending>,
173    pool: Vec<Vec<u8>>,
174    channels: Vec<Vec<u8>>,
175    patterns: Vec<Vec<u8>>,
176    subscriber: bool,
177    deadline: Option<Instant>,
178    attempt: u32,
179}
180impl Connection {
181    pub fn new(config: Config) -> Self {
182        Self {
183            config,
184            state: State::Disconnected,
185            resp3: false,
186            handshake: Handshake::Hello,
187            tx: Vec::with_capacity(4096),
188            tx_pos: 0,
189            rx: Vec::with_capacity(4096),
190            events: VecDeque::with_capacity(32),
191            pending: VecDeque::with_capacity(32),
192            offline: VecDeque::with_capacity(32),
193            pool: Vec::with_capacity(32),
194            channels: Vec::new(),
195            patterns: Vec::new(),
196            subscriber: false,
197            deadline: None,
198            attempt: 0,
199        }
200    }
201    pub fn state(&self) -> State {
202        self.state
203    }
204    pub fn poll_event(&mut self) -> Option<Event> {
205        self.events.pop_front()
206    }
207    pub fn output(&self) -> &[u8] {
208        &self.tx[self.tx_pos..]
209    }
210    pub fn consume_output(&mut self, count: usize) {
211        assert!(count <= self.output().len());
212        self.tx_pos += count;
213        if self.tx_pos == self.tx.len() {
214            self.tx.clear();
215            self.tx_pos = 0;
216        }
217    }
218    pub fn connect(&mut self, now: Instant) -> Result<(), Error> {
219        if !matches!(
220            self.state,
221            State::Disconnected | State::Closed | State::WaitingRetry
222        ) {
223            return Err(Error::new("Redis is already connecting/connected"));
224        }
225        self.rx.clear();
226        self.state = State::Connecting;
227        self.deadline = now.checked_add(self.config.connect_timeout);
228        self.events.push_back(Event::Connect);
229        Ok(())
230    }
231    pub fn transport_connected(&mut self) -> Result<(), Error> {
232        if self.state != State::Connecting {
233            return Err(Error::new("Unexpected connection"));
234        }
235        if self.config.tls {
236            self.state = State::Tls;
237            self.events.push_back(Event::UpgradeTls);
238        } else {
239            self.begin_handshake();
240        }
241        Ok(())
242    }
243    pub fn tls_established(&mut self) -> Result<(), Error> {
244        if self.state != State::Tls {
245            return Err(Error::new("Unexpected TLS completion"));
246        }
247        self.begin_handshake();
248        Ok(())
249    }
250    fn begin_handshake(&mut self) {
251        self.state = State::Handshake;
252        self.resp3 = false;
253        self.subscriber = false;
254        if self.config.prefer_resp3 {
255            self.handshake = Handshake::Hello;
256            if let Some(password) = &self.config.password {
257                encode_command(
258                    &[
259                        b"HELLO",
260                        b"3",
261                        b"AUTH",
262                        self.config
263                            .username
264                            .as_deref()
265                            .unwrap_or("default")
266                            .as_bytes(),
267                        password.as_bytes(),
268                    ],
269                    &mut self.tx,
270                );
271            } else {
272                encode_command(&[b"HELLO", b"3"], &mut self.tx);
273            }
274        } else {
275            self.auth();
276        }
277    }
278    fn auth(&mut self) {
279        self.handshake = Handshake::Auth;
280        if let Some(password) = &self.config.password {
281            if let Some(user) = &self.config.username {
282                encode_command(
283                    &[b"AUTH", user.as_bytes(), password.as_bytes()],
284                    &mut self.tx,
285                );
286            } else {
287                encode_command(&[b"AUTH", password.as_bytes()], &mut self.tx);
288            }
289        } else {
290            self.select();
291        }
292    }
293    fn select(&mut self) {
294        self.handshake = Handshake::Select;
295        if self.config.database != 0 {
296            encode_command(
297                &[b"SELECT", self.config.database.to_string().as_bytes()],
298                &mut self.tx,
299            );
300        } else {
301            self.name();
302        }
303    }
304    fn name(&mut self) {
305        self.handshake = Handshake::Name;
306        if let Some(name) = &self.config.client_name {
307            encode_command(&[b"CLIENT", b"SETNAME", name.as_bytes()], &mut self.tx);
308        } else {
309            self.restore();
310        }
311    }
312    fn restore(&mut self) {
313        self.handshake = Handshake::Restore;
314        if self.config.auto_resubscribe {
315            for (kind, items) in [
316                (Kind::Subscribe, &self.channels),
317                (Kind::Psubscribe, &self.patterns),
318            ] {
319                for item in items {
320                    let mut wire = self.pool.pop().unwrap_or_default();
321                    wire.clear();
322                    encode_command(
323                        &[
324                            if kind == Kind::Subscribe {
325                                b"SUBSCRIBE"
326                            } else {
327                                b"PSUBSCRIBE"
328                            },
329                            item,
330                        ],
331                        &mut wire,
332                    );
333                    self.tx.extend_from_slice(&wire);
334                    self.pending.push_back(Pending {
335                        token: None,
336                        wire,
337                        deadline: None,
338                        kind,
339                        acks: 1,
340                    });
341                }
342            }
343            self.subscriber = !self.pending.is_empty();
344        } else {
345            self.channels.clear();
346            self.patterns.clear();
347        }
348        if self.pending.is_empty() {
349            self.ready();
350        }
351    }
352    fn ready(&mut self) {
353        self.state = State::Ready;
354        self.deadline = None;
355        self.attempt = 0;
356        self.refresh_subscriber();
357        self.events.push_back(Event::Ready { resp3: self.resp3 });
358        while let Some(p) = self.offline.pop_front() {
359            self.tx.extend_from_slice(&p.wire);
360            self.pending.push_back(p);
361        }
362    }
363    /// `deadline` is host policy, including commandTimeout or blocking-command
364    /// protection. Redis's own BLPOP timeout remains in the command arguments.
365    pub fn command(
366        &mut self,
367        token: u64,
368        args: &[&[u8]],
369        deadline: Option<Instant>,
370    ) -> Result<(), Error> {
371        let name = args.first().ok_or_else(|| Error::new("Empty command"))?;
372        if self
373            .pending
374            .iter()
375            .chain(&self.offline)
376            .any(|p| p.token == Some(token))
377        {
378            return Err(Error::new("Duplicate command token"));
379        }
380        if matches!(self.state, State::Closed) {
381            return Err(Error::new("Connection is closed."));
382        }
383        if self.state != State::Ready && !self.config.offline_queue {
384            return Err(Error::new(
385                "Stream isn't writeable and enableOfflineQueue options is false",
386            ));
387        }
388        let kind = Kind::of(name);
389        if self.subscriber
390            && !(kind.subscription() || kind == Kind::Quit || name.eq_ignore_ascii_case(b"PING"))
391        {
392            return Err(Error::new(
393                "Connection in subscriber mode, only subscriber commands may be used",
394            ));
395        }
396        if matches!(kind, Kind::Subscribe | Kind::Psubscribe) {
397            self.subscriber = true;
398        }
399        let acks = if args.len() > 1 {
400            args.len() - 1
401        } else {
402            match kind {
403                Kind::Unsubscribe | Kind::Punsubscribe => usize::MAX,
404                _ => 1,
405            }
406        };
407        let mut wire = self.pool.pop().unwrap_or_default();
408        wire.clear();
409        encode_command(args, &mut wire);
410        let p = Pending {
411            token: Some(token),
412            wire,
413            deadline,
414            kind,
415            acks,
416        };
417        if self.state == State::Ready {
418            self.tx.extend_from_slice(&p.wire);
419            self.pending.push_back(p);
420        } else {
421            self.offline.push_back(p);
422        }
423        Ok(())
424    }
425    pub fn receive(&mut self, bytes: &[u8]) -> Result<(), Error> {
426        if !matches!(self.state, State::Ready | State::Handshake) {
427            return Err(Error::new("Bytes outside Redis protocol state"));
428        }
429        // Limit buffering even when the host supplies many frames at once.
430        for chunk in bytes.chunks(4096) {
431            self.rx.extend_from_slice(chunk);
432            let mut consumed = 0;
433            loop {
434                if self.state == State::Ready
435                    && (self.subscriber || self.rx.get(consumed) == Some(&b'>'))
436                {
437                    match resp::message(&self.rx[consumed..], self.config.limits) {
438                        Ok(Some((message, len))) => {
439                            self.events.push_back(Event::Message {
440                                pattern: message.pattern.map(<[u8]>::to_vec),
441                                channel: message.channel.to_vec(),
442                                payload: message.payload.to_vec(),
443                            });
444                            consumed += len;
445                            continue;
446                        }
447                        Ok(None) => {}
448                        Err(e) => {
449                            let error = Error::new(&e.to_string());
450                            self.close();
451                            return Err(error);
452                        }
453                    }
454                }
455                match resp::decode(&self.rx[consumed..], self.config.limits) {
456                    Ok(Some((value, n))) => {
457                        consumed += n;
458                        if let Err(error) = self.frame(value) {
459                            self.close();
460                            return Err(error);
461                        }
462                        if self.state == State::Closed {
463                            return Ok(());
464                        }
465                    }
466                    Ok(None) => break,
467                    Err(e) => {
468                        let error = Error::new(&e.to_string());
469                        self.close();
470                        return Err(error);
471                    }
472                }
473            }
474            self.rx.drain(..consumed);
475        }
476        Ok(())
477    }
478    fn frame(&mut self, value: Value) -> Result<(), Error> {
479        if let Value::Attribute(_, value) = value {
480            return self.frame(*value);
481        }
482        if self.state == State::Handshake && !matches!(self.handshake, Handshake::Restore) {
483            if let Value::Error(bytes) = value {
484                if matches!(self.handshake, Handshake::Hello)
485                    && (bytes.starts_with(b"ERR unknown command") || bytes.starts_with(b"NOPROTO"))
486                {
487                    self.auth();
488                    return Ok(());
489                }
490                self.events.push_back(Event::Error(Error::reply(bytes)));
491                self.close();
492                return Ok(());
493            }
494            match self.handshake {
495                Handshake::Hello => {
496                    self.resp3 = true;
497                    self.select();
498                }
499                Handshake::Auth => self.select(),
500                Handshake::Select => self.name(),
501                Handshake::Name => self.restore(),
502                Handshake::Restore => unreachable!(),
503            }
504            return Ok(());
505        }
506        let pubsub = matches!(value, Value::Push(_))
507            || (self.subscriber && matches!(value, Value::Array(_)));
508        if pubsub {
509            if let Some(items) = value.items() {
510                let tag = items.first().and_then(Value::bytes).unwrap_or_default();
511                if (tag == b"message" && items.len() == 3)
512                    || (tag == b"pmessage" && items.len() == 4)
513                {
514                    let mut items = match value {
515                        Value::Array(v) | Value::Push(v) => v,
516                        _ => unreachable!(),
517                    };
518                    let payload = take_bytes(items.pop().unwrap())?;
519                    let channel = take_bytes(items.pop().unwrap())?;
520                    let pattern = if items.len() == 2 {
521                        Some(take_bytes(items.pop().unwrap())?)
522                    } else {
523                        None
524                    };
525                    self.events.push_back(Event::Message {
526                        pattern,
527                        channel,
528                        payload,
529                    });
530                    return Ok(());
531                }
532                let kind = Kind::of(tag);
533                if kind.subscription() && items.len() == 3 {
534                    let target = if matches!(kind, Kind::Psubscribe | Kind::Punsubscribe) {
535                        &mut self.patterns
536                    } else {
537                        &mut self.channels
538                    };
539                    if let Some(channel) = items[1].bytes() {
540                        if matches!(kind, Kind::Subscribe | Kind::Psubscribe) {
541                            if !target.iter().any(|v| v == channel) {
542                                target.push(channel.to_vec());
543                            }
544                        } else {
545                            target.retain(|v| v != channel);
546                        }
547                    }
548                    let empty = target.is_empty();
549                    let count = items[2]
550                        .integer()
551                        .ok_or_else(|| Error::new("Invalid subscription count"))?;
552                    self.subscriber = count != 0;
553                    if let Some(p) = self.pending.front_mut().filter(|p| p.kind == kind) {
554                        let done = if p.acks == usize::MAX {
555                            empty
556                        } else {
557                            p.acks = p.acks.saturating_sub(1);
558                            p.acks == 0
559                        };
560                        if done {
561                            self.complete(Value::Integer(count))?;
562                        }
563                        if self.state == State::Handshake && self.pending.is_empty() {
564                            self.ready();
565                        }
566                    } else {
567                        return Err(Error::new("Unexpected subscription acknowledgement"));
568                    }
569                    return Ok(());
570                }
571                if tag == b"pong" && !self.resp3 {
572                    // RESP2 subscriber PING returns [pong, payload].
573                    let pong = items
574                        .get(1)
575                        .and_then(Value::bytes)
576                        .unwrap_or_default()
577                        .to_vec();
578                    self.complete(Value::Bulk(pong))?;
579                    return Ok(());
580                }
581            }
582            if matches!(value, Value::Push(_)) {
583                self.events.push_back(Event::Push(value));
584                return Ok(());
585            }
586        }
587        self.complete(value)
588    }
589    fn complete(&mut self, value: Value) -> Result<(), Error> {
590        let p = self
591            .pending
592            .pop_front()
593            .ok_or_else(|| Error::new("Unexpected Redis reply"))?;
594        if let Some(token) = p.token {
595            let result = if let Value::Error(bytes) = value {
596                Err(Error::reply(bytes))
597            } else {
598                Ok(value)
599            };
600            self.events.push_back(Event::Reply { token, result });
601        }
602        self.pool.push(p.wire);
603        self.refresh_subscriber();
604        if p.kind == Kind::Quit {
605            self.close();
606        }
607        Ok(())
608    }
609    fn refresh_subscriber(&mut self) {
610        self.subscriber = !self.channels.is_empty()
611            || !self.patterns.is_empty()
612            || self
613                .pending
614                .iter()
615                .chain(&self.offline)
616                .any(|p| matches!(p.kind, Kind::Subscribe | Kind::Psubscribe));
617    }
618    pub fn next_timeout(&self) -> Option<Instant> {
619        self.deadline
620            .into_iter()
621            .chain(
622                self.pending
623                    .iter()
624                    .chain(&self.offline)
625                    .filter_map(|p| p.deadline),
626            )
627            .min()
628    }
629    pub fn handle_timeout(&mut self, now: Instant) {
630        for p in &mut self.pending {
631            if p.deadline.is_some_and(|d| d <= now) {
632                p.deadline = None;
633                if let Some(token) = p.token.take() {
634                    self.events.push_back(Event::Reply {
635                        token,
636                        result: Err(Error::new("Command timed out")),
637                    });
638                }
639            }
640        }
641        let mut i = 0;
642        while i < self.offline.len() {
643            if self.offline[i].deadline.is_some_and(|d| d <= now) {
644                let p = self.offline.remove(i).unwrap();
645                if let Some(token) = p.token {
646                    self.events.push_back(Event::Reply {
647                        token,
648                        result: Err(Error::new("Command timed out")),
649                    });
650                }
651                self.pool.push(p.wire);
652            } else {
653                i += 1;
654            }
655        }
656        if self.deadline.is_some_and(|d| d <= now) {
657            self.deadline = None;
658            if self.state == State::WaitingRetry {
659                let _ = self.connect(now);
660            } else {
661                self.events
662                    .push_back(Event::Error(Error::new("connect ETIMEDOUT")));
663                self.transport_lost();
664            }
665        }
666    }
667    /// Call once per failed transport, including DNS/connect/TLS failures. The
668    /// host closes the socket on CloseTransport before accepting new Connect.
669    pub fn transport_lost(&mut self) {
670        if matches!(
671            self.state,
672            State::Closed | State::RetryDecision | State::WaitingRetry
673        ) {
674            return;
675        }
676        self.tx.clear();
677        self.tx_pos = 0;
678        self.rx.clear();
679        self.deadline = None;
680        while let Some(p) = self.pending.pop_back() {
681            if self.config.auto_resend_unfulfilled && p.token.is_some() {
682                self.offline.push_front(p);
683            } else {
684                self.fail_pending(p, "Connection is closed.");
685            }
686        }
687        self.attempt = self.attempt.saturating_add(1);
688        if self
689            .config
690            .max_retries_per_request
691            .is_some_and(|n| self.attempt > n)
692        {
693            while let Some(p) = self.offline.pop_front() {
694                self.fail_pending(p, "Reached the max retries per request limit");
695            }
696        }
697        self.state = State::RetryDecision;
698        self.events.push_back(Event::CloseTransport);
699        self.events.push_back(Event::Retry {
700            attempt: self.attempt,
701        });
702    }
703    pub fn retry(&mut self, now: Instant, delay: Option<Duration>) -> Result<(), Error> {
704        if self.state != State::RetryDecision {
705            return Err(Error::new("No retry decision requested"));
706        }
707        if let Some(delay) = delay {
708            self.state = State::WaitingRetry;
709            self.deadline = now.checked_add(delay);
710        } else {
711            self.close();
712        }
713        Ok(())
714    }
715    fn fail_pending(&mut self, p: Pending, message: &str) {
716        if let Some(token) = p.token {
717            self.events.push_back(Event::Reply {
718                token,
719                result: Err(Error::new(message)),
720            });
721        }
722        self.pool.push(p.wire);
723    }
724    pub fn close(&mut self) {
725        if self.state == State::Closed {
726            return;
727        }
728        while let Some(p) = self.pending.pop_front() {
729            self.fail_pending(p, "Connection is closed.");
730        }
731        while let Some(p) = self.offline.pop_front() {
732            self.fail_pending(p, "Connection is closed.");
733        }
734        self.state = State::Closed;
735        self.deadline = None;
736        self.tx.clear();
737        self.tx_pos = 0;
738        self.channels.clear();
739        self.patterns.clear();
740        self.subscriber = false;
741        self.events.push_back(Event::CloseTransport);
742        self.events.push_back(Event::Closed);
743    }
744}
745fn take_bytes(value: Value) -> Result<Vec<u8>, Error> {
746    match value {
747        Value::Bulk(v) | Value::Simple(v) => Ok(v),
748        _ => Err(Error::new("Invalid pub/sub message")),
749    }
750}
751
752#[cfg(feature = "turnloop")]
753pub mod asynchronous;