Skip to main content

cortexkit_bus_client/
lib.rs

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