#![doc = include_str!("../README.md")]
mod binding;
mod buckets;
mod credentials;
mod events;
pub use buckets::{Bucket, BucketEntry, BucketItem, BucketWatch};
pub use events::{EventDelivery, EventItem, EventReader, MalformedDelivery, MalformedReason};
use std::{
sync::{Arc, RwLock},
time::Duration,
};
use bytes::Bytes;
use cortexkit_bus_naming::{validate_token, AccountNames, TokenKind};
use cortexkit_bus_nats::{ConnectConfig, NatsConnection};
use cortexkit_bus_trait::{ContentDigest, Headers, PublishReceipt, Stream};
const CONTENT_DIGEST_HEADER: &str = "Ck-Content-Digest";
use subc_client_rs::SubcConsumer;
use tokio::sync::watch;
use credentials::{CredentialManager, SubcTransport};
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
#[error("ck-bus refused the request: {0}")]
Refused(String),
#[error("ck-bus request failed: {0}")]
Transport(String),
#[error("invalid ck-bus reply: {0}")]
Reply(&'static str),
#[error(transparent)]
Naming(#[from] cortexkit_bus_naming::NamingError),
#[error(transparent)]
Bus(#[from] cortexkit_bus_trait::BusError),
#[error("NATS operation failed: {0}")]
Nats(String),
#[error("event body is {size} bytes; the maximum is 4096 bytes")]
EventBodyTooLarge { size: usize },
#[error("durable {durable} is not owned by module {module}")]
DurableNotOwned { durable: String, module: String },
#[error("module bucket {owner}.{bucket} is not declared")]
BucketNotDeclared { owner: String, bucket: String },
#[error("module {module} may not read bucket {bucket}")]
BucketNotReadable { module: String, bucket: String },
#[error("module {module} does not own bucket {bucket}")]
BucketNotOwned { module: String, bucket: String },
#[error("bucket value is {size} bytes; the maximum is {cap} bytes")]
BucketValueTooLarge { size: usize, cap: u32 },
#[error("bucket {bucket} has no watch consumer slots available")]
WatchCapacity { bucket: String },
}
pub type Result<T> = std::result::Result<T, Error>;
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct BusClientOptions {
module: String,
pub request_timeout: Duration,
}
impl BusClientOptions {
pub fn new(module: impl Into<String>) -> Result<Self> {
let module = module.into();
validate_token(TokenKind::ModuleId, &module)?;
Ok(Self {
module,
request_timeout: Duration::from_secs(5),
})
}
}
pub struct BusClient {
connection: Arc<RwLock<NatsConnection>>,
names: AccountNames,
module: String,
changes: watch::Receiver<u64>,
task: tokio::task::JoinHandle<()>,
}
impl Drop for BusClient {
fn drop(&mut self) {
self.task.abort();
}
}
impl BusClient {
pub async fn connect(subc: Arc<SubcConsumer>, opts: BusClientOptions) -> Result<Self> {
let transport = SubcTransport::new(subc, &opts.module, opts.request_timeout);
static MANAGERS: std::sync::LazyLock<
tokio::sync::Mutex<
std::collections::HashMap<String, std::sync::Weak<CredentialManager>>,
>,
> = std::sync::LazyLock::new(Default::default);
let mut managers = MANAGERS.lock().await;
let manager = match managers
.get(&opts.module)
.and_then(std::sync::Weak::upgrade)
{
Some(manager) => manager,
None => {
let manager = CredentialManager::start(Arc::new(transport)).await?;
managers.insert(opts.module.clone(), Arc::downgrade(&manager));
manager
}
};
drop(managers);
Self::connect_manager(manager, opts).await
}
async fn connect_manager(
manager: Arc<CredentialManager>,
opts: BusClientOptions,
) -> Result<Self> {
let mut revisions = manager.revisions();
let initial = manager.credential().await;
let names = AccountNames::derive(&initial.acct)?;
let (connection, mut ended) = loop {
revisions.borrow_and_update();
let credential = manager.credential().await;
match connect_current(manager.clone(), &credential, opts.request_timeout).await {
Ok(current) if !revisions.has_changed().unwrap_or(false) => break current,
Ok((connection, _)) => {
let _ = connection.close(Duration::from_millis(50)).await;
}
Err(_)
if manager.credential().await.credential_public
!= credential.credential_public => {}
Err(error) => return Err(error),
}
};
let connection = Arc::new(RwLock::new(connection));
let shared = connection.clone();
let (changes, receiver) = watch::channel(0);
let task = tokio::spawn(async move {
let mut retry = None;
loop {
let credential = manager.credential().await;
let delay = retry
.take()
.unwrap_or_else(|| credentials::renewal_delay(credential.exp));
tokio::select! {
result = revisions.changed() => { if result.is_err() { return; } }
() = connection_ended(&mut ended) => {
tracing::warn!("bus connection closed for good; replacing it");
}
() = tokio::time::sleep(delay) => {
if let Err(error) = manager.renew().await {
if credentials::transient(&error) || matches!(error, Error::Transport(_)) {
retry = Some(Duration::from_secs(5));
continue;
}
let refusal_code = match &error {
Error::Refused(code) => code.as_str(),
_ => "client_renewal_error",
};
tracing::warn!(
refusal_code,
"bus credential maintenance stopped; reconnect or report degraded"
);
return;
}
if !revisions.has_changed().unwrap_or(false) { continue; }
}
}
let mut backoff = Duration::from_millis(250);
loop {
let revision = *revisions.borrow_and_update();
let credential = manager.credential().await;
match connect_current(manager.clone(), &credential, opts.request_timeout).await
{
Ok((replacement, replacement_ended)) => {
if revisions.has_changed().unwrap_or(false) {
let _ = replacement.close(Duration::from_millis(50)).await;
continue;
}
let old = {
let mut slot = shared
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
std::mem::replace(&mut *slot, replacement)
};
ended = replacement_ended;
changes.send_replace(revision);
let _ = old.close(Duration::from_millis(50)).await;
break;
}
Err(_) => {
tokio::time::sleep(backoff).await;
backoff = (backoff * 2).min(Duration::from_secs(30));
}
}
}
}
});
Ok(Self {
connection,
names,
module: opts.module,
changes: receiver,
task,
})
}
pub fn connection(&self) -> NatsConnection {
self.connection
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
pub fn connection_changes(&self) -> watch::Receiver<u64> {
self.changes.clone()
}
pub fn acct(&self) -> &str {
self.names.account()
}
pub fn box_id(&self) -> Option<cortexkit_bus_naming::federation::BoxId> {
credentials::box_id(self.acct())
}
pub fn inbox_prefix(&self) -> String {
self.connection().inbox_prefix().to_owned()
}
pub async fn event_reader(&self, durable: &str) -> Result<EventReader> {
EventReader::attach(self, durable).await
}
pub fn bucket(&self, owner_module: &str, bucket: &str) -> Result<Bucket> {
Bucket::attach(self, owner_module, bucket)
}
pub async fn publish_event(
&self,
event: &str,
version: u32,
qualifier: Option<&str>,
msg_id: &str,
body: impl Into<Bytes>,
) -> Result<PublishReceipt> {
let body = body.into();
if body.len() > 4096 {
return Err(Error::EventBodyTooLarge { size: body.len() });
}
let subject = self.event_subject(event, version, qualifier)?;
let mut headers = async_nats::HeaderMap::new();
headers.insert(async_nats::header::NATS_MESSAGE_ID, msg_id);
if !body.is_empty() {
headers.insert(
CONTENT_DIGEST_HEADER,
ContentDigest::of_bytes(&body).to_string().as_str(),
);
}
let ack = async_nats::jetstream::new(self.connection().client())
.publish_with_headers(subject, headers, body)
.await
.map_err(|error| Error::Nats(error.to_string()))?
.await
.map_err(|error| Error::Nats(error.to_string()))?;
Ok(PublishReceipt::new(ack.sequence, ack.duplicate))
}
#[allow(clippy::too_many_arguments)]
pub async fn publish_claim_check(
&self,
event: &str,
version: u32,
qualifier: Option<&str>,
msg_id: &str,
digest: ContentDigest,
headers: Headers,
) -> Result<PublishReceipt> {
let subject = self.event_subject(event, version, qualifier)?;
self.connection()
.stream(&self.names.streams().event)
.publish(&subject, msg_id, digest, headers)
.await
.map_err(Error::from)
}
fn event_subject(&self, event: &str, version: u32, qualifier: Option<&str>) -> Result<String> {
Ok(match qualifier {
Some(reader) => {
self.names
.event_subject_with_reader(&self.module, event, version, reader)?
}
None => self.names.event_subject(&self.module, event, version)?,
})
}
pub async fn live_hint(&self, kind: &str, version: u32, body: impl Into<Bytes>) -> Result<()> {
let subject = self.names.live_subject(&self.module, kind, version)?;
self.connection()
.client()
.publish(subject, body.into())
.await
.map_err(|error| Error::Nats(error.to_string()))
}
}
const MAX_RECONNECTS: usize = 20;
pub(crate) const LIVENESS_SUBJECT: &str = "bus-client-liveness";
async fn connection_ended(ended: &mut async_nats::Subscriber) {
use futures_util::StreamExt;
while ended.next().await.is_some() {}
}
async fn connect_current(
manager: Arc<CredentialManager>,
credential: &credentials::Credential,
timeout: Duration,
) -> Result<(NatsConnection, async_nats::Subscriber)> {
let public = credential.credential_public.clone();
let options = async_nats::ConnectOptions::with_auth_callback(move |nonce| {
let manager = manager.clone();
let public = public.clone();
let task = tokio::spawn(async move {
let credential = manager.credential().await;
if credential.credential_public != public {
return Err(Error::Reply("connection credential was replaced"));
}
let signature = manager.sign(&public, nonce).await?;
let mut auth = async_nats::Auth::new();
auth.jwt = Some(credential.jwt);
auth.signature = Some(signature);
Ok(auth)
});
async move {
task.await
.map_err(async_nats::AuthError::new)?
.map_err(async_nats::AuthError::new)
}
})
.connection_timeout(timeout)
.request_timeout(Some(timeout))
.max_reconnects(MAX_RECONNECTS);
let mut config = ConnectConfig::new(&credential.credential_public)?;
config.request_timeout = timeout;
let connection = if credential.inbox_prefix == config.inbox_prefix() {
NatsConnection::connect(credential.server_url.as_str(), options, config).await
} else {
NatsConnection::connect_with_inbox_prefix(
credential.server_url.as_str(),
options,
config,
&credential.inbox_prefix,
)
.await
}
.map_err(Error::from)?;
let subject = format!("{}.{LIVENESS_SUBJECT}", connection.inbox_prefix());
match connection.client().subscribe(subject).await {
Ok(ended) => Ok((connection, ended)),
Err(error) => {
let _ = connection.close(Duration::from_millis(50)).await;
Err(Error::Nats(error.to_string()))
}
}
}
#[cfg(test)]
mod tests;