pg_bus/subscription.rs
1//! A subscriber: the backlog from its position first, then the live feed.
2//!
3//! The feed is joined before the backlog is read, so a message is in one
4//! or the other (or both, and then skipped the second time: delivery is in
5//! position order, and anything at or before the position has been seen).
6//! A subscriber that falls more than the feed's capacity behind goes back
7//! to the backlog from its position.
8
9use std::collections::VecDeque;
10use std::sync::Arc;
11
12use tokio::sync::broadcast;
13use tokio::sync::broadcast::error::RecvError;
14
15use crate::stats::Counters;
16use crate::{Bus, Error, Filter, Message, Position};
17
18/// Messages read from the backlog per query.
19const BATCH: i64 = 500;
20
21/// What a subscription yields.
22#[derive(Debug, Clone, PartialEq)]
23pub enum Item {
24 Message(Message),
25 /// Messages after the starting position were trimmed from the backlog
26 /// before they could be read: the subscriber has missed some and should
27 /// reload its state. Yielded once, first; delivery goes on after it.
28 Gap,
29}
30
31pub struct Subscription {
32 bus: Bus,
33 filter: Filter,
34 position: Position,
35 feed: broadcast::Receiver<Arc<Message>>,
36 queue: VecDeque<Message>,
37 catching_up: bool,
38 gap_checked: bool,
39}
40
41impl Subscription {
42 pub(crate) fn new(bus: Bus, from: Position, filter: Filter) -> Subscription {
43 let feed = bus.feed();
44 Subscription {
45 bus,
46 filter,
47 position: from,
48 feed,
49 queue: VecDeque::new(),
50 catching_up: true,
51 gap_checked: false,
52 }
53 }
54
55 /// The last position this subscription has passed, delivered or not:
56 /// resuming from it misses nothing.
57 pub fn position(&self) -> Position {
58 self.position
59 }
60
61 /// The next item, waiting for one if none is due.
62 ///
63 /// Cancel-safe: state only changes after each await completes, so
64 /// dropping the future (a timeout) loses nothing and the next call
65 /// picks up where this one was.
66 pub async fn next(&mut self) -> Result<Item, Error> {
67 if !self.gap_checked {
68 // Held in memory from here on: nothing after it was trimmed
69 // away, and no query is needed to say so.
70 let in_memory = self
71 .bus
72 .recent_after(self.position, &self.filter, 0)
73 .is_some();
74 let trimmed = !in_memory && self.bus.trimmed_after(self.position).await?;
75 self.gap_checked = true;
76 if trimmed {
77 return Ok(Item::Gap);
78 }
79 }
80 loop {
81 if let Some(message) = self.queue.pop_front() {
82 // Delivery is in strictly increasing position: anything
83 // else is a bug, loud in tests, skipped in release.
84 if message.position <= self.position {
85 debug_assert!(
86 false,
87 "pg-bus: {} delivered after {} ({})",
88 message.position, self.position, message.channel
89 );
90 Counters::add(&self.bus.counters().out_of_order, 1);
91 tracing::error!(
92 "pg-bus: skipped {} after {}: out of order",
93 message.position,
94 self.position
95 );
96 continue;
97 }
98 self.position = message.position;
99 return Ok(Item::Message(message));
100 }
101 if self.catching_up {
102 // From memory when this process still holds everything after
103 // the position, else from the backlog table.
104 let batch = match self
105 .bus
106 .recent_after(self.position, &self.filter, BATCH as usize)
107 {
108 Some(batch) => {
109 Counters::add(&self.bus.counters().catch_ups_from_memory, 1);
110 batch
111 }
112 None => {
113 let batch = self.bus.backlog(self.position, &self.filter, BATCH).await?;
114 Counters::add(&self.bus.counters().catch_ups_from_database, 1);
115 tracing::debug!(
116 "pg-bus: caught up {} message(s) from the backlog table after {}",
117 batch.len(),
118 self.position
119 );
120 batch
121 }
122 };
123 if (batch.len() as i64) < BATCH {
124 self.catching_up = false;
125 }
126 self.queue.extend(batch);
127 continue;
128 }
129 match self.feed.recv().await {
130 Ok(message) => {
131 if message.position <= self.position {
132 continue;
133 }
134 if self.filter.matches(&message) {
135 self.queue.push_back((*message).clone());
136 } else {
137 self.position = message.position;
138 }
139 }
140 // Fell behind the feed: the backlog has everything after
141 // the position.
142 Err(RecvError::Lagged(n)) => {
143 Counters::add(&self.bus.counters().lagged, 1);
144 tracing::debug!("pg-bus: subscriber fell {n} message(s) behind the feed");
145 self.catching_up = true;
146 }
147 Err(RecvError::Closed) => return Err(Error::Closed),
148 }
149 }
150 }
151}