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#[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#[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
78pub 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 pub async fn connect(subc: Arc<SubcConsumer>, opts: BusClientOptions) -> Result<Self> {
97 let transport = SubcTransport::new(subc, &opts.module, opts.request_timeout);
98 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 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 pub fn connection(&self) -> NatsConnection {
215 self.connection
216 .read()
217 .unwrap_or_else(std::sync::PoisonError::into_inner)
218 .clone()
219 }
220
221 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 pub async fn event_reader(&self, durable: &str) -> Result<EventReader> {
244 EventReader::attach(self, durable).await
245 }
246
247 pub fn bucket(&self, owner_module: &str, bucket: &str) -> Result<Bucket> {
250 Bucket::attach(self, owner_module, bucket)
251 }
252
253 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 #[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 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 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;