1#![deny(unsafe_op_in_unsafe_fn)]
2pub 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 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 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 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 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 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;