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};
20
21const CONTENT_DIGEST_HEADER: &str = "Ck-Content-Digest";
24use subc_client_rs::SubcConsumer;
25use tokio::sync::watch;
26
27use credentials::{CredentialManager, SubcTransport};
28
29#[derive(Debug, thiserror::Error)]
31#[non_exhaustive]
32pub enum Error {
33 #[error("ck-bus refused the request: {0}")]
34 Refused(String),
35 #[error("ck-bus request failed: {0}")]
36 Transport(String),
37 #[error("invalid ck-bus reply: {0}")]
38 Reply(&'static str),
39 #[error(transparent)]
40 Naming(#[from] cortexkit_bus_naming::NamingError),
41 #[error(transparent)]
42 Bus(#[from] cortexkit_bus_trait::BusError),
43 #[error("NATS operation failed: {0}")]
44 Nats(String),
45 #[error("event body is {size} bytes; the maximum is 4096 bytes")]
46 EventBodyTooLarge { size: usize },
47 #[error("durable {durable} is not owned by module {module}")]
48 DurableNotOwned { durable: String, module: String },
49 #[error("module bucket {owner}.{bucket} is not declared")]
50 BucketNotDeclared { owner: String, bucket: String },
51 #[error("module {module} may not read bucket {bucket}")]
52 BucketNotReadable { module: String, bucket: String },
53 #[error("module {module} does not own bucket {bucket}")]
54 BucketNotOwned { module: String, bucket: String },
55 #[error("bucket value is {size} bytes; the maximum is {cap} bytes")]
56 BucketValueTooLarge { size: usize, cap: u32 },
57 #[error("bucket {bucket} has no watch consumer slots available")]
58 WatchCapacity { bucket: String },
59}
60
61pub type Result<T> = std::result::Result<T, Error>;
62
63#[derive(Clone, Debug)]
65#[non_exhaustive]
66pub struct BusClientOptions {
67 module: String,
68 pub request_timeout: Duration,
69}
70
71impl BusClientOptions {
72 pub fn new(module: impl Into<String>) -> Result<Self> {
73 let module = module.into();
74 validate_token(TokenKind::ModuleId, &module)?;
75 Ok(Self {
76 module,
77 request_timeout: Duration::from_secs(5),
78 })
79 }
80}
81
82pub struct BusClient {
84 connection: Arc<RwLock<NatsConnection>>,
85 names: AccountNames,
86 module: String,
87 changes: watch::Receiver<u64>,
88 task: tokio::task::JoinHandle<()>,
89}
90
91impl Drop for BusClient {
92 fn drop(&mut self) {
93 self.task.abort();
94 }
95}
96
97impl BusClient {
98 pub async fn connect(subc: Arc<SubcConsumer>, opts: BusClientOptions) -> Result<Self> {
101 let transport = SubcTransport::new(subc, &opts.module, opts.request_timeout);
102 static MANAGERS: std::sync::LazyLock<
105 tokio::sync::Mutex<
106 std::collections::HashMap<String, std::sync::Weak<CredentialManager>>,
107 >,
108 > = std::sync::LazyLock::new(Default::default);
109 let mut managers = MANAGERS.lock().await;
110 let manager = match managers
111 .get(&opts.module)
112 .and_then(std::sync::Weak::upgrade)
113 {
114 Some(manager) => manager,
115 None => {
116 let manager = CredentialManager::start(Arc::new(transport)).await?;
117 managers.insert(opts.module.clone(), Arc::downgrade(&manager));
118 manager
119 }
120 };
121 drop(managers);
122 Self::connect_manager(manager, opts).await
123 }
124
125 async fn connect_manager(
126 manager: Arc<CredentialManager>,
127 opts: BusClientOptions,
128 ) -> Result<Self> {
129 let mut revisions = manager.revisions();
130 let initial = manager.credential().await;
131 let names = AccountNames::derive(&initial.acct)?;
132 let (connection, mut ended) = loop {
133 revisions.borrow_and_update();
134 let credential = manager.credential().await;
135 match connect_current(manager.clone(), &credential, opts.request_timeout).await {
136 Ok(current) if !revisions.has_changed().unwrap_or(false) => break current,
137 Ok((connection, _)) => {
138 let _ = connection.close(Duration::from_millis(50)).await;
139 }
140 Err(_)
141 if manager.credential().await.credential_public
142 != credential.credential_public => {}
143 Err(error) => return Err(error),
144 }
145 };
146 let connection = Arc::new(RwLock::new(connection));
147 let shared = connection.clone();
148 let (changes, receiver) = watch::channel(0);
149 let task = tokio::spawn(async move {
150 let mut retry = None;
151 loop {
152 let credential = manager.credential().await;
153 let delay = retry
154 .take()
155 .unwrap_or_else(|| credentials::renewal_delay(credential.exp));
156 tokio::select! {
157 result = revisions.changed() => { if result.is_err() { return; } }
158 () = connection_ended(&mut ended) => {
159 tracing::warn!("bus connection closed for good; replacing it");
162 }
163 () = tokio::time::sleep(delay) => {
164 if let Err(error) = manager.renew().await {
165 if credentials::transient(&error) || matches!(error, Error::Transport(_)) {
166 retry = Some(Duration::from_secs(5));
167 continue;
168 }
169 let refusal_code = match &error {
172 Error::Refused(code) => code.as_str(),
173 _ => "client_renewal_error",
174 };
175 tracing::warn!(
176 refusal_code,
177 "bus credential maintenance stopped; reconnect or report degraded"
178 );
179 return;
180 }
181 if !revisions.has_changed().unwrap_or(false) { continue; }
182 }
183 }
184 let mut backoff = Duration::from_millis(250);
185 loop {
186 let revision = *revisions.borrow_and_update();
187 let credential = manager.credential().await;
188 match connect_current(manager.clone(), &credential, opts.request_timeout).await
189 {
190 Ok((replacement, replacement_ended)) => {
191 if revisions.has_changed().unwrap_or(false) {
192 let _ = replacement.close(Duration::from_millis(50)).await;
193 continue;
194 }
195 let old = {
196 let mut slot = shared
197 .write()
198 .unwrap_or_else(std::sync::PoisonError::into_inner);
199 std::mem::replace(&mut *slot, replacement)
200 };
201 ended = replacement_ended;
202 changes.send_replace(revision);
203 let _ = old.close(Duration::from_millis(50)).await;
207 break;
208 }
209 Err(_) => {
210 tokio::time::sleep(backoff).await;
211 backoff = (backoff * 2).min(Duration::from_secs(30));
212 }
213 }
214 }
215 }
216 });
217 Ok(Self {
218 connection,
219 names,
220 module: opts.module,
221 changes: receiver,
222 task,
223 })
224 }
225
226 pub fn connection(&self) -> NatsConnection {
228 self.connection
229 .read()
230 .unwrap_or_else(std::sync::PoisonError::into_inner)
231 .clone()
232 }
233
234 pub fn connection_changes(&self) -> watch::Receiver<u64> {
243 self.changes.clone()
244 }
245
246 pub fn acct(&self) -> &str {
247 self.names.account()
248 }
249
250 pub async fn event_reader(&self, durable: &str) -> Result<EventReader> {
257 EventReader::attach(self, durable).await
258 }
259
260 pub fn bucket(&self, owner_module: &str, bucket: &str) -> Result<Bucket> {
263 Bucket::attach(self, owner_module, bucket)
264 }
265
266 pub async fn publish_event(
282 &self,
283 event: &str,
284 version: u32,
285 qualifier: Option<&str>,
286 msg_id: &str,
287 body: impl Into<Bytes>,
288 ) -> Result<PublishReceipt> {
289 let body = body.into();
290 if body.len() > 4096 {
291 return Err(Error::EventBodyTooLarge { size: body.len() });
292 }
293 let subject = self.event_subject(event, version, qualifier)?;
294 let mut headers = async_nats::HeaderMap::new();
295 headers.insert(async_nats::header::NATS_MESSAGE_ID, msg_id);
296 if !body.is_empty() {
297 headers.insert(
298 CONTENT_DIGEST_HEADER,
299 ContentDigest::of_bytes(&body).to_string().as_str(),
300 );
301 }
302 let ack = async_nats::jetstream::new(self.connection().client())
303 .publish_with_headers(subject, headers, body)
304 .await
305 .map_err(|error| Error::Nats(error.to_string()))?
306 .await
307 .map_err(|error| Error::Nats(error.to_string()))?;
308 Ok(PublishReceipt::new(ack.sequence, ack.duplicate))
309 }
310
311 #[allow(clippy::too_many_arguments)]
318 pub async fn publish_claim_check(
319 &self,
320 event: &str,
321 version: u32,
322 qualifier: Option<&str>,
323 msg_id: &str,
324 digest: ContentDigest,
325 headers: Headers,
326 ) -> Result<PublishReceipt> {
327 let subject = self.event_subject(event, version, qualifier)?;
328 self.connection()
329 .stream(&self.names.streams().event)
330 .publish(&subject, msg_id, digest, headers)
331 .await
332 .map_err(Error::from)
333 }
334
335 fn event_subject(&self, event: &str, version: u32, qualifier: Option<&str>) -> Result<String> {
336 Ok(match qualifier {
337 Some(reader) => {
338 self.names
339 .event_subject_with_reader(&self.module, event, version, reader)?
340 }
341 None => self.names.event_subject(&self.module, event, version)?,
342 })
343 }
344
345 pub async fn live_hint(&self, kind: &str, version: u32, body: impl Into<Bytes>) -> Result<()> {
347 let subject = self.names.live_subject(&self.module, kind, version)?;
348 self.connection()
349 .client()
350 .publish(subject, body.into())
351 .await
352 .map_err(|error| Error::Nats(error.to_string()))
353 }
354}
355
356const MAX_RECONNECTS: usize = 20;
366
367pub(crate) const LIVENESS_SUBJECT: &str = "bus-client-liveness";
371
372async fn connection_ended(ended: &mut async_nats::Subscriber) {
381 use futures_util::StreamExt;
382 while ended.next().await.is_some() {}
383}
384
385async fn connect_current(
386 manager: Arc<CredentialManager>,
387 credential: &credentials::Credential,
388 timeout: Duration,
389) -> Result<(NatsConnection, async_nats::Subscriber)> {
390 let public = credential.credential_public.clone();
391 let options = async_nats::ConnectOptions::with_auth_callback(move |nonce| {
392 let manager = manager.clone();
393 let public = public.clone();
394 let task = tokio::spawn(async move {
397 let credential = manager.credential().await;
398 if credential.credential_public != public {
399 return Err(Error::Reply("connection credential was replaced"));
400 }
401 let signature = manager.sign(&public, nonce).await?;
402 let mut auth = async_nats::Auth::new();
403 auth.jwt = Some(credential.jwt);
404 auth.signature = Some(signature);
405 Ok(auth)
406 });
407 async move {
408 task.await
409 .map_err(async_nats::AuthError::new)?
410 .map_err(async_nats::AuthError::new)
411 }
412 })
413 .connection_timeout(timeout)
414 .request_timeout(Some(timeout))
415 .max_reconnects(MAX_RECONNECTS);
416 let mut config = ConnectConfig::new(&credential.credential_public)?;
417 config.request_timeout = timeout;
418 let connection = NatsConnection::connect(credential.server_url.as_str(), options, config)
419 .await
420 .map_err(Error::from)?;
421 let subject = format!("{}.{LIVENESS_SUBJECT}", connection.inbox_prefix());
422 match connection.client().subscribe(subject).await {
423 Ok(ended) => Ok((connection, ended)),
424 Err(error) => {
425 let _ = connection.close(Duration::from_millis(50)).await;
426 Err(Error::Nats(error.to_string()))
427 }
428 }
429}
430
431#[cfg(test)]
432mod tests;