Skip to main content

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}