Skip to main content

cortexkit_bus_client/
lib.rs

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