Skip to main content

cortexkit_bus_client/
events.rs

1use std::time::Duration;
2
3use async_nats::jetstream::{self, consumer::pull, AckKind};
4use bytes::Bytes;
5use cortexkit_bus_naming::{AccountNames, EventSubject};
6use cortexkit_bus_trait::Headers;
7use futures_util::StreamExt;
8
9use crate::{binding::ConnectionBinding, BusClient, Error, Result};
10
11/// One EVENT pull result. Malformed records can only be terminated, not acked.
12#[non_exhaustive]
13pub enum EventItem {
14    Delivery(EventDelivery),
15    Malformed(MalformedDelivery),
16}
17
18/// A stored event. Commit your own transaction before calling [`Self::ack`].
19/// Dropping a delivery does not acknowledge it; the server may redeliver it.
20#[non_exhaustive]
21pub struct EventDelivery {
22    pub subject: EventSubject,
23    pub msg_id: String,
24    pub body: Bytes,
25    pub stream_sequence: u64,
26    pub delivered_count: i64,
27    headers: Headers,
28    message: jetstream::Message,
29}
30
31impl EventDelivery {
32    /// Headers copied once from NATS. A repeated header keeps its first value.
33    pub fn headers(&self) -> &Headers {
34        &self.headers
35    }
36
37    /// Looks up a header by its stored name, keeping the first repeated value.
38    pub fn header(&self, name: &str) -> Option<&str> {
39        self.headers.get(name).map(String::as_str)
40    }
41
42    /// Acknowledges the event after the caller's own commit, waiting for the
43    /// server to confirm receipt. No reader operation acknowledges automatically.
44    pub async fn ack(&self) -> Result<()> {
45        self.message
46            .double_ack()
47            .await
48            .map_err(|error| Error::Nats(error.to_string()))
49    }
50
51    /// Requests redelivery after a delay (zero requests immediate redelivery).
52    pub async fn nak(&self, delay: Duration) -> Result<()> {
53        self.message
54            .double_ack_with(AckKind::Nak(Some(delay)))
55            .await
56            .map_err(|error| Error::Nats(error.to_string()))
57    }
58
59    /// Permanently stops redelivery of this event.
60    pub async fn term(&self) -> Result<()> {
61        terminate(&self.message).await
62    }
63}
64
65/// Why a stored record cannot be exposed as a valid event.
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67#[non_exhaustive]
68pub enum MalformedReason {
69    MissingMsgId,
70    BadSubject,
71    BadMetadata,
72}
73
74/// A malformed record. Log the reason and call [`Self::term`] to prevent retries.
75/// Nothing, including malformed records, is acknowledged automatically.
76#[non_exhaustive]
77pub struct MalformedDelivery {
78    pub raw_subject: String,
79    pub reason: MalformedReason,
80    /// Absent only when the server supplied malformed JetStream metadata.
81    pub stream_sequence: Option<u64>,
82    message: jetstream::Message,
83}
84
85impl MalformedDelivery {
86    /// Permanently stops redelivery of a malformed record.
87    pub async fn term(&self) -> Result<()> {
88        terminate(&self.message).await
89    }
90}
91
92async fn terminate(message: &jetstream::Message) -> Result<()> {
93    message
94        .double_ack_with(AckKind::Term)
95        .await
96        .map_err(|error| Error::Nats(error.to_string()))
97}
98
99/// A one-at-a-time reader of an existing module-owned EVENT durable.
100/// The server owns its cursor. Re-issue rebinds the reader to the same durable;
101/// unacknowledged messages may redeliver. Keep the [`BusClient`] alive so its
102/// credential maintenance continues to run.
103pub struct EventReader {
104    binding: ConnectionBinding,
105    names: AccountNames,
106    durable: String,
107    consumer: Option<jetstream::consumer::Consumer<pull::Config>>,
108}
109
110impl EventReader {
111    pub(crate) async fn attach(client: &BusClient, durable: &str) -> Result<Self> {
112        let base = AccountNames::module_consumer_name(&client.module)?;
113        // EventConsumer::durable_name accepts only static declarations; apply
114        // the same owner rule directly to a runtime durable name.
115        if durable != base
116            && !durable
117                .strip_prefix(&format!("{base}_"))
118                .is_some_and(|suffix| {
119                    !suffix.is_empty()
120                        && suffix.bytes().all(|byte| {
121                            byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_'
122                        })
123                })
124        {
125            return Err(Error::DurableNotOwned {
126                durable: durable.into(),
127                module: client.module.clone(),
128            });
129        }
130        let mut reader = Self {
131            binding: ConnectionBinding::new(client),
132            names: client.names.clone(),
133            durable: durable.into(),
134            consumer: None,
135        };
136        reader.bind().await?;
137        Ok(reader)
138    }
139
140    async fn bind(&mut self) -> Result<()> {
141        let durable = &self.durable;
142        let stream = &self.names.streams().event;
143        self.consumer = Some(
144            self.binding
145                .bind(|connection| async move {
146                    jetstream::new(connection.client())
147                        .get_consumer_from_stream(durable, stream)
148                        .await
149                        .map_err(|error| Error::Nats(error.to_string()))
150                })
151                .await?,
152        );
153        Ok(())
154    }
155
156    /// Pulls one event, rebinding after credential re-issue if necessary.
157    /// This never acknowledges a message. Commit before acknowledging a valid
158    /// delivery; log and terminate a malformed record instead of retrying it.
159    /// A closed connection-change stream reports a transport error so the caller
160    /// can reconnect the client or report degraded credential maintenance.
161    pub async fn next(&mut self) -> Result<EventItem> {
162        loop {
163            if self.binding.has_changed() || self.consumer.is_none() {
164                self.bind().await?;
165            }
166            let consumer = self.consumer.as_ref().expect("bound consumer");
167            tokio::select! {
168                biased;
169                changed = self.binding.changed() => {
170                    changed?;
171                    self.consumer = None;
172                }
173                result = async {
174                    let mut batch = consumer.fetch().max_messages(1)
175                        .expires(Duration::from_secs(30)).messages().await
176                        .map_err(|error| Error::Nats(error.to_string()))?;
177                    batch.next().await.transpose().map_err(|error| Error::Nats(error.to_string()))
178                } => {
179                    if let Some(message) = result? {
180                        return Ok(decode(&self.names, message));
181                    }
182                }
183            }
184        }
185    }
186}
187
188fn decode(names: &AccountNames, message: jetstream::Message) -> EventItem {
189    let metadata = message.info();
190    let stream_sequence = metadata.as_ref().ok().map(|info| info.stream_sequence);
191    let subject = names.parse_event_subject(message.subject.as_str());
192    let headers: Headers = message
193        .headers
194        .as_ref()
195        .into_iter()
196        .flat_map(|headers| headers.iter())
197        .filter_map(|(name, values)| {
198            values
199                .first()
200                .map(|value| (name.to_string(), value.to_string()))
201        })
202        .collect();
203    let msg_id = message.headers.as_ref().and_then(|headers| {
204        headers
205            .get(async_nats::header::NATS_MESSAGE_ID)
206            .map(|value| value.as_str().to_owned())
207    });
208    let reason = if metadata.is_err() {
209        Some(MalformedReason::BadMetadata)
210    } else if subject.is_err() {
211        Some(MalformedReason::BadSubject)
212    } else if msg_id.is_none() {
213        Some(MalformedReason::MissingMsgId)
214    } else {
215        None
216    };
217    if let Some(reason) = reason {
218        return EventItem::Malformed(MalformedDelivery {
219            raw_subject: message.subject.to_string(),
220            reason,
221            stream_sequence,
222            message,
223        });
224    }
225    let delivered_count = metadata.expect("validated metadata").delivered;
226    EventItem::Delivery(EventDelivery {
227        subject: subject.expect("validated subject"),
228        msg_id: msg_id.expect("validated msg id"),
229        body: message.payload.clone(),
230        stream_sequence: stream_sequence.expect("validated sequence"),
231        delivered_count,
232        headers,
233        message,
234    })
235}