Skip to main content

cortexkit_bus_client/
lib.rs

1#![doc = include_str!("../README.md")]
2
3mod credentials;
4mod events;
5
6pub use events::{EventDelivery, EventItem, EventReader, MalformedDelivery, MalformedReason};
7
8use std::{
9    sync::{Arc, RwLock},
10    time::Duration,
11};
12
13use bytes::Bytes;
14use cortexkit_bus_naming::{validate_token, AccountNames, TokenKind};
15use cortexkit_bus_nats::{ConnectConfig, NatsConnection};
16use cortexkit_bus_trait::PublishReceipt;
17use subc_client_rs::SubcConsumer;
18use tokio::sync::watch;
19
20use credentials::{CredentialManager, SubcTransport};
21
22/// Errors contain refusal codes, not credential JWTs or nonce signatures.
23#[derive(Debug, thiserror::Error)]
24#[non_exhaustive]
25pub enum Error {
26    #[error("ck-bus refused the request: {0}")]
27    Refused(String),
28    #[error("ck-bus request failed: {0}")]
29    Transport(String),
30    #[error("invalid ck-bus reply: {0}")]
31    Reply(&'static str),
32    #[error(transparent)]
33    Naming(#[from] cortexkit_bus_naming::NamingError),
34    #[error(transparent)]
35    Bus(#[from] cortexkit_bus_trait::BusError),
36    #[error("NATS operation failed: {0}")]
37    Nats(String),
38    #[error("event body is {size} bytes; the maximum is 4096 bytes")]
39    EventBodyTooLarge { size: usize },
40    #[error("durable {durable} is not owned by module {module}")]
41    DurableNotOwned { durable: String, module: String },
42}
43
44pub type Result<T> = std::result::Result<T, Error>;
45
46/// Options for one module's bus connection.
47#[derive(Clone, Debug)]
48#[non_exhaustive]
49pub struct BusClientOptions {
50    module: String,
51    pub request_timeout: Duration,
52}
53
54impl BusClientOptions {
55    pub fn new(module: impl Into<String>) -> Result<Self> {
56        let module = module.into();
57        validate_token(TokenKind::ModuleId, &module)?;
58        Ok(Self {
59            module,
60            request_timeout: Duration::from_secs(5),
61        })
62    }
63}
64
65/// A module's current connection and the task that maintains its credentials.
66pub struct BusClient {
67    connection: Arc<RwLock<NatsConnection>>,
68    names: AccountNames,
69    module: String,
70    changes: watch::Receiver<u64>,
71    task: tokio::task::JoinHandle<()>,
72}
73
74impl Drop for BusClient {
75    fn drop(&mut self) {
76        self.task.abort();
77    }
78}
79
80impl BusClient {
81    /// Issues a credential for the module identity that the subc daemon
82    /// authenticates from the module's launch nonce.
83    pub async fn connect(subc: Arc<SubcConsumer>, opts: BusClientOptions) -> Result<Self> {
84        let transport = SubcTransport::new(subc, &opts.module, opts.request_timeout);
85        // One module process can keep several connection snapshots, but issuing
86        // independently for them would revoke the other snapshots' credentials.
87        static MANAGERS: std::sync::LazyLock<
88            tokio::sync::Mutex<
89                std::collections::HashMap<String, std::sync::Weak<CredentialManager>>,
90            >,
91        > = std::sync::LazyLock::new(Default::default);
92        let mut managers = MANAGERS.lock().await;
93        let manager = match managers
94            .get(&opts.module)
95            .and_then(std::sync::Weak::upgrade)
96        {
97            Some(manager) => manager,
98            None => {
99                let manager = CredentialManager::start(Arc::new(transport)).await?;
100                managers.insert(opts.module.clone(), Arc::downgrade(&manager));
101                manager
102            }
103        };
104        drop(managers);
105        Self::connect_manager(manager, opts).await
106    }
107
108    async fn connect_manager(
109        manager: Arc<CredentialManager>,
110        opts: BusClientOptions,
111    ) -> Result<Self> {
112        let mut revisions = manager.revisions();
113        let initial = manager.credential().await;
114        let names = AccountNames::derive(&initial.acct)?;
115        let connection = loop {
116            revisions.borrow_and_update();
117            let credential = manager.credential().await;
118            match connect_current(manager.clone(), &credential, opts.request_timeout).await {
119                Ok(connection) if !revisions.has_changed().unwrap_or(false) => break connection,
120                Ok(connection) => {
121                    let _ = connection.close(Duration::from_millis(50)).await;
122                }
123                Err(_)
124                    if manager.credential().await.credential_public
125                        != credential.credential_public => {}
126                Err(error) => return Err(error),
127            }
128        };
129        let connection = Arc::new(RwLock::new(connection));
130        let shared = connection.clone();
131        let (changes, receiver) = watch::channel(0);
132        let task = tokio::spawn(async move {
133            let mut retry = None;
134            loop {
135                let credential = manager.credential().await;
136                let delay = retry
137                    .take()
138                    .unwrap_or_else(|| credentials::renewal_delay(credential.exp));
139                tokio::select! {
140                    result = revisions.changed() => { if result.is_err() { return; } }
141                    () = tokio::time::sleep(delay) => {
142                        if let Err(error) = manager.renew().await {
143                            if credentials::transient(&error) || matches!(error, Error::Transport(_)) {
144                                retry = Some(Duration::from_secs(5));
145                                continue;
146                            }
147                            // A terminal refusal (notably generation_not_live)
148                            // must not cause issuance under a dead generation.
149                            let refusal_code = match &error {
150                                Error::Refused(code) => code.as_str(),
151                                _ => "client_renewal_error",
152                            };
153                            tracing::warn!(
154                                refusal_code,
155                                "bus credential maintenance stopped; reconnect or report degraded"
156                            );
157                            return;
158                        }
159                        if !revisions.has_changed().unwrap_or(false) { continue; }
160                    }
161                }
162                let mut backoff = Duration::from_millis(250);
163                loop {
164                    let revision = *revisions.borrow_and_update();
165                    let credential = manager.credential().await;
166                    match connect_current(manager.clone(), &credential, opts.request_timeout).await
167                    {
168                        Ok(replacement) => {
169                            if revisions.has_changed().unwrap_or(false) {
170                                let _ = replacement.close(Duration::from_millis(50)).await;
171                                continue;
172                            }
173                            let old = {
174                                let mut slot = shared
175                                    .write()
176                                    .unwrap_or_else(std::sync::PoisonError::into_inner);
177                                std::mem::replace(&mut *slot, replacement)
178                            };
179                            changes.send_replace(revision);
180                            let _ = old.close(Duration::from_millis(50)).await;
181                            break;
182                        }
183                        Err(_) => {
184                            tokio::time::sleep(backoff).await;
185                            backoff = (backoff * 2).min(Duration::from_secs(30));
186                        }
187                    }
188                }
189            }
190        });
191        Ok(Self {
192            connection,
193            names,
194            module: opts.module,
195            changes: receiver,
196            task,
197        })
198    }
199
200    /// Returns a snapshot. A re-issue does not change an already held snapshot.
201    pub fn connection(&self) -> NatsConnection {
202        self.connection
203            .read()
204            .unwrap_or_else(std::sync::PoisonError::into_inner)
205            .clone()
206    }
207
208    /// Changes only after a replacement connection with a new inbox is ready.
209    /// Reopen raw subscriptions and durable pulls when this receiver changes;
210    /// [`EventReader`] handles its own rebinding automatically.
211    ///
212    /// If credential maintenance can no longer renew or re-issue, its task ends
213    /// and drops the sender. The receiver's `changed()` then returns `Err` once
214    /// any unseen change has been consumed. Reconnect with [`BusClient::connect`]
215    /// or report the module as degraded when the change stream closes.
216    pub fn connection_changes(&self) -> watch::Receiver<u64> {
217        self.changes.clone()
218    }
219
220    pub fn acct(&self) -> &str {
221        self.names.account()
222    }
223
224    /// Attaches to an existing EVENT durable owned by this module.
225    ///
226    /// ck-bus provisions durables; this method never creates or changes one.
227    /// The name must follow bus-naming's `m_{module}[_suffix]` owner rule.
228    /// The reader rebinds automatically after credential re-issue. Nothing is
229    /// acknowledged automatically: commit your own transaction before `ack()`.
230    pub async fn event_reader(&self, durable: &str) -> Result<EventReader> {
231        EventReader::attach(self, durable).await
232    }
233
234    /// Stores an event using the fact's own id for JetStream deduplication.
235    ///
236    /// Event bodies carry ids, counters and enums, not large content. Bodies
237    /// larger than 4 KiB are refused; retrieve large content through its owner's
238    /// own call instead.
239    pub async fn publish_event(
240        &self,
241        event: &str,
242        version: u32,
243        qualifier: Option<&str>,
244        msg_id: &str,
245        body: impl Into<Bytes>,
246    ) -> Result<PublishReceipt> {
247        let body = body.into();
248        if body.len() > 4096 {
249            return Err(Error::EventBodyTooLarge { size: body.len() });
250        }
251        let subject = match qualifier {
252            Some(reader) => {
253                self.names
254                    .event_subject_with_reader(&self.module, event, version, reader)?
255            }
256            None => self.names.event_subject(&self.module, event, version)?,
257        };
258        let mut headers = async_nats::HeaderMap::new();
259        headers.insert(async_nats::header::NATS_MESSAGE_ID, msg_id);
260        let ack = async_nats::jetstream::new(self.connection().client())
261            .publish_with_headers(subject, headers, body)
262            .await
263            .map_err(|error| Error::Nats(error.to_string()))?
264            .await
265            .map_err(|error| Error::Nats(error.to_string()))?;
266        Ok(PublishReceipt::new(ack.sequence, ack.duplicate))
267    }
268
269    /// Publishes an ephemeral, versioned hint, not a stored fact.
270    pub async fn live_hint(&self, kind: &str, version: u32, body: impl Into<Bytes>) -> Result<()> {
271        let subject = self.names.live_subject(&self.module, kind, version)?;
272        self.connection()
273            .client()
274            .publish(subject, body.into())
275            .await
276            .map_err(|error| Error::Nats(error.to_string()))
277    }
278}
279
280async fn connect_current(
281    manager: Arc<CredentialManager>,
282    credential: &credentials::Credential,
283    timeout: Duration,
284) -> Result<NatsConnection> {
285    let public = credential.credential_public.clone();
286    let options = async_nats::ConnectOptions::with_auth_callback(move |nonce| {
287        let manager = manager.clone();
288        let public = public.clone();
289        // The spawned subc request future only needs to be Send; async-nats
290        // also requires the callback future to be Sync.
291        let task = tokio::spawn(async move {
292            let credential = manager.credential().await;
293            if credential.credential_public != public {
294                return Err(Error::Reply("connection credential was replaced"));
295            }
296            let signature = manager.sign(&public, nonce).await?;
297            let mut auth = async_nats::Auth::new();
298            auth.jwt = Some(credential.jwt);
299            auth.signature = Some(signature);
300            Ok(auth)
301        });
302        async move {
303            task.await
304                .map_err(async_nats::AuthError::new)?
305                .map_err(async_nats::AuthError::new)
306        }
307    })
308    .connection_timeout(timeout)
309    .request_timeout(Some(timeout));
310    let mut config = ConnectConfig::new(&credential.credential_public)?;
311    config.request_timeout = timeout;
312    NatsConnection::connect(credential.server_url.as_str(), options, config)
313        .await
314        .map_err(Error::from)
315}
316
317#[cfg(test)]
318mod tests;