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#[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#[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
65pub 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 pub async fn connect(subc: Arc<SubcConsumer>, opts: BusClientOptions) -> Result<Self> {
84 let transport = SubcTransport::new(subc, &opts.module, opts.request_timeout);
85 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 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 pub fn connection(&self) -> NatsConnection {
202 self.connection
203 .read()
204 .unwrap_or_else(std::sync::PoisonError::into_inner)
205 .clone()
206 }
207
208 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 pub async fn event_reader(&self, durable: &str) -> Result<EventReader> {
231 EventReader::attach(self, durable).await
232 }
233
234 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 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 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;