mod book;
mod cadence;
mod chain;
mod gojson;
mod handover;
mod handover_tie;
#[cfg(test)]
mod handover_tie_tests;
mod handover_times;
mod held;
mod history;
#[cfg(test)]
mod hooks_tests;
mod import;
mod lock;
mod log;
mod push;
mod random;
mod receive;
#[cfg(test)]
mod receive_tests;
mod record_time;
#[cfg(test)]
mod record_time_tests;
mod records;
mod sent;
mod stamp;
mod stamp_proof;
mod store;
mod time;
mod tree;
pub use book::{BookEntry, BookRecord, Indexes, ShelfBook, RECORD_HEADER_MEMBER};
pub use cadence::{
Cadence, CadenceConfig, CadenceTick, TickResult, WitnessCheck, WitnessReceipt, WITNESS_INVALID,
WITNESS_NOT_CHECKED, WITNESS_VERIFIED,
};
pub use chain::CADENCE_EXTENSION;
pub use handover::{
verify_handover, ConsistencyEvidence, Handover, HandoverCheckpoint, HandoverConsistency,
HandoverDocument, HandoverLatest, HandoverResult,
};
pub use handover_tie::HandoverTie;
pub use handover_times::{verify_handover_times, HandoverTimes};
pub use held::HeldProof;
pub use history::StandardHistoryAnchor;
pub const JOURNAL_LOG_ID: &str = "journal";
pub use import::LegacyCadence;
pub use log::{Checkpoint, SUBSTRATE_KIND_CLL};
pub use push::{
push_a2a_extension, PushA2a, PushA2aRequest, PushA2aResponse, PushMcp, A2A_PROTOCOL_VERSION,
A2A_PUSH_EXTENSION_URI, MCP_PROTOCOL_VERSION, MCP_TOOL_RECORD_PUSH,
};
pub use random::{RandomSource, SeededStream, SystemRandom};
pub use receive::{
CountedPrefix, Evidence, HeldRecord, ProofOutcome, ReceiveBounds, ReceiveChanges,
ReceiveConfig, ReceiveError, ReceiveProfile, ReceiveResult, ReceivedRecord, RecordOutcome,
EVIDENCE_CHECKPOINT, EVIDENCE_CHECKPOINT_RECORDS, EVIDENCE_FORK,
};
pub use records::{ShelfRecord, ShelfRecords};
pub use sent::{SealedSent, SentCapsule};
pub use stamp::{AudienceFact, BatchEntry, BookStatus, StampBatch, StatusInput, StatusValues};
pub use stamp_proof::{verify_stamp_proof, InclusionEvidence, StampProof, VerifiedStampProof};
pub use store::{StoredRecord, SHELF_VERSION, SHELF_VERSION_FACTS};
pub use time::Time;
pub use tree::{
cadence_empty, cadence_filler_leaf, cadence_fold, cadence_leaf, cadence_tree, derived_fillers,
padding_record_id, TickLeaf, TickLeaves, CADENCE_DEPTH,
};
use self::lock::FileLock;
use self::log::Log;
use self::random::Draws;
use self::store::{KIND_BOOK, KIND_HOST, KIND_JOURNAL};
use crate::substrate::Signer;
use capsule_emit_artifact::Store as ArtifactStore;
use ed25519_dalek::SigningKey;
use rusqlite::Connection;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, Mutex, MutexGuard};
use std::time::{Duration, Instant};
#[derive(Debug, thiserror::Error)]
pub enum ShelfError {
#[error("invalid: {0}")]
Invalid(String),
#[error("corrupt: {0}")]
Corrupt(String),
#[error("not found: {0}")]
NotFound(String),
#[error("not covered: {0}")]
NotCovered(String),
#[error("unsupported: {0}")]
Unsupported(String),
#[error("over the item limit: {0}")]
OverLimit(String),
#[error("the shelf is released")]
Released,
#[error("refused: {0}")]
Refused(String),
#[error("deleted: {0}")]
Deleted(String),
#[error("payload unavailable: {0}")]
Unavailable(String),
#[error("busy; try again: {0}")]
Busy(String),
#[error("receive profile: {0}")]
Profile(String),
#[error("{0}: another writer holds it")]
LockHeld(String),
#[error("log: {0}")]
Log(String),
#[error("originals: {0}")]
Artifact(String),
#[error("{0}")]
Random(String),
#[error(transparent)]
Seal(#[from] crate::seal::SealRecordError),
#[error("sqlite: {0}")]
Sqlite(#[from] rusqlite::Error),
#[error("io: {0}")]
Io(#[from] std::io::Error),
}
pub trait HeldLock: Send + Sync {
fn held(&self) -> Result<(), String>;
}
impl<T: HeldLock + ?Sized> HeldLock for Arc<T> {
fn held(&self) -> Result<(), String> {
(**self).held()
}
}
pub type Clock = Arc<dyn Fn() -> Time + Send + Sync>;
pub type IndexChoice = Arc<dyn Fn(&str) -> Indexes + Send + Sync>;
pub struct ShelfConfig {
pub path: PathBuf,
pub lock_path: Option<PathBuf>,
pub held_lock: Option<Box<dyn HeldLock>>,
pub lock_timeout: Option<Duration>,
pub random: Option<Box<dyn RandomSource>>,
pub operator: String,
pub developer: String,
pub signer: Arc<dyn Signer + Send + Sync>,
pub checkpoint_key: SigningKey,
pub originals: Arc<dyn ArtifactStore + Send + Sync>,
pub now: Option<Clock>,
pub authenticated_indexes: Option<IndexChoice>,
pub correlation_members: Vec<String>,
pub receive: ReceiveConfig,
}
pub(crate) struct ShelfShared {
pub(crate) path: PathBuf,
pub(crate) operator: String,
pub(crate) developer: String,
pub(crate) signer: Arc<dyn Signer + Send + Sync>,
pub(crate) checkpoint_key: SigningKey,
pub(crate) originals: Arc<dyn ArtifactStore + Send + Sync>,
now: Option<Clock>,
authenticated: Option<IndexChoice>,
pub(crate) correlation_members: Vec<String>,
pub(crate) receive: ReceiveConfig,
pub(crate) receive_mu: Mutex<()>,
pub(crate) closed: AtomicBool,
db: Mutex<Connection>,
}
impl ShelfShared {
pub(crate) fn now(&self) -> Time {
self.now.as_ref().map_or_else(Time::now, |f| f())
}
pub(crate) fn db(&self) -> MutexGuard<'_, Connection> {
self.db.lock().unwrap_or_else(|p| p.into_inner())
}
}
pub(crate) struct HostCore {
pub(crate) id: String,
pub(crate) log: Arc<Log>,
pub(crate) in_cadence: bool,
}
pub(crate) struct ShelfState {
pub(crate) books: HashMap<String, ShelfBook>,
pub(crate) hosts: HashMap<String, Arc<HostCore>>,
pub(crate) cadence: Option<(String, Arc<Log>)>,
pub(crate) random: Draws,
pub(crate) released: bool,
lock: Option<FileLock>,
}
pub(crate) struct ShelfInner {
pub(crate) shared: Arc<ShelfShared>,
pub(crate) state: Mutex<ShelfState>,
}
#[derive(Clone)]
pub struct Shelf(pub(crate) Arc<ShelfInner>);
#[derive(Clone)]
pub struct WeakShelf(std::sync::Weak<ShelfInner>);
impl WeakShelf {
pub fn upgrade(&self) -> Option<Shelf> {
self.0.upgrade().map(Shelf)
}
}
impl Shelf {
pub fn open_sqlite(cfg: ShelfConfig) -> Result<Shelf, ShelfError> {
if cfg.path.as_os_str().is_empty() || cfg.operator.is_empty() {
return Err(ShelfError::Invalid("path and operator are required".into()));
}
let lock = match &cfg.held_lock {
Some(held) => {
if cfg.lock_path.is_some() {
return Err(ShelfError::Invalid(
"a shelf on a host-held lock takes no lock path".into(),
));
}
held.held().map_err(|e| {
ShelfError::Invalid(format!("the host's writer lock is not held: {e}"))
})?;
None
}
None => {
let path = cfg.lock_path.clone().unwrap_or_else(|| {
let mut p = cfg.path.clone().into_os_string();
p.push(".lock");
PathBuf::from(p)
});
Some(FileLock::acquire(
&path,
cfg.lock_timeout.map(|t| Instant::now() + t),
)?)
}
};
let mut conn = Connection::open(&cfg.path)?;
conn.busy_timeout(Duration::from_millis(5000))?;
conn.pragma_update(None, "journal_mode", "WAL")?;
conn.pragma_update(None, "synchronous", "FULL")?;
store::init(&mut conn)?;
let shared = Arc::new(ShelfShared {
path: cfg.path,
operator: cfg.operator,
developer: cfg.developer,
signer: cfg.signer,
checkpoint_key: cfg.checkpoint_key,
originals: cfg.originals,
now: cfg.now,
authenticated: cfg.authenticated_indexes,
correlation_members: cfg.correlation_members,
receive: cfg.receive,
receive_mu: Mutex::new(()),
closed: AtomicBool::new(false),
db: Mutex::new(conn),
});
Ok(Shelf(Arc::new(ShelfInner {
shared,
state: Mutex::new(ShelfState {
books: HashMap::new(),
hosts: HashMap::new(),
cadence: None,
random: Draws(cfg.random.unwrap_or_else(|| Box::new(SystemRandom))),
released: false,
lock,
}),
})))
}
pub fn downgrade(&self) -> WeakShelf {
WeakShelf(Arc::downgrade(&self.0))
}
pub(crate) fn lock(&self) -> MutexGuard<'_, ShelfState> {
self.0.state.lock().unwrap_or_else(|p| p.into_inner())
}
pub(crate) fn shared(&self) -> &Arc<ShelfShared> {
&self.0.shared
}
pub fn path(&self) -> &Path {
&self.0.shared.path
}
pub fn open(&self, log_id: &str) -> Result<ShelfBook, ShelfError> {
let mut state = self.lock();
if state.released {
return Err(ShelfError::Released);
}
if store::log_kind(&self.shared().db(), log_id)?.as_deref() == Some(KIND_JOURNAL) {
return Err(ShelfError::Invalid(format!(
"{log_id} is the shelf's journal; open it with journal"
)));
}
self.open_locked(&mut state, log_id)
}
pub fn journal(&self) -> Result<ShelfBook, ShelfError> {
let mut state = self.lock();
if state.released {
return Err(ShelfError::Released);
}
let shared = self.shared().clone();
if let Some(book) = state.books.get(JOURNAL_LOG_ID) {
if store::log_kind(&shared.db(), JOURNAL_LOG_ID)?.as_deref() == Some(KIND_JOURNAL) {
return Ok(book.clone());
}
return Err(ShelfError::Invalid(format!(
"{JOURNAL_LOG_ID} is already a book, not the journal"
)));
}
if stamp::migration_state(&shared.db())? != stamp::MIGRATION_DONE {
return Err(ShelfError::Invalid(
"the journal needs a shelf of book facts; call migrate".into(),
));
}
if state.hosts.contains_key(JOURNAL_LOG_ID) {
return Err(ShelfError::Invalid(format!(
"{JOURNAL_LOG_ID} is a host log, not the journal"
)));
}
if state
.cadence
.as_ref()
.is_some_and(|(id, _)| id == JOURNAL_LOG_ID)
{
return Err(ShelfError::Invalid(format!(
"{JOURNAL_LOG_ID} is the cadence log, not the journal"
)));
}
{
let mut db = shared.db();
let tx = store::write_tx(&mut db)?;
let records = store::record_count(&tx, JOURNAL_LOG_ID)?;
let kind = store::log_kind(&tx, JOURNAL_LOG_ID)?;
if kind.as_deref() != Some(KIND_JOURNAL) && (kind.is_some() || records > 0) {
return Err(ShelfError::Invalid(format!(
"{JOURNAL_LOG_ID} is already a {} log, not the journal",
kind.as_deref().unwrap_or(KIND_BOOK)
)));
}
if kind.is_none() {
let entries: i64 = tx.query_row(
"SELECT COUNT(*) FROM cll_entries WHERE log_id = ?",
[JOURNAL_LOG_ID],
|r| r.get(0),
)?;
if entries > 0 {
return Err(ShelfError::Invalid(format!(
"{JOURNAL_LOG_ID} already holds another log's entries, not the journal"
)));
}
}
store::allow_journal_kind(&tx)?;
store::claim_kind(&tx, JOURNAL_LOG_ID, KIND_JOURNAL)?;
tx.commit()?;
}
self.open_locked(&mut state, JOURNAL_LOG_ID)
}
pub fn existing_journal(&self) -> Result<Option<ShelfBook>, ShelfError> {
let mut state = self.lock();
if state.released {
return Err(ShelfError::Released);
}
self.existing_journal_locked(&mut state)
}
pub(crate) fn existing_journal_locked(
&self,
state: &mut ShelfState,
) -> Result<Option<ShelfBook>, ShelfError> {
let shared = self.shared().clone();
if stamp::migration_state(&shared.db())? != stamp::MIGRATION_DONE {
return Ok(None);
}
let kind = store::log_kind(&shared.db(), JOURNAL_LOG_ID)?;
if kind.as_deref() != Some(KIND_JOURNAL) {
return Ok(None);
}
self.open_locked(state, JOURNAL_LOG_ID).map(Some)
}
pub(crate) fn open_locked(
&self,
state: &mut ShelfState,
log_id: &str,
) -> Result<ShelfBook, ShelfError> {
if state.released {
return Err(ShelfError::Released);
}
if let Some(book) = state.books.get(log_id) {
return Ok(book.clone());
}
let shared = self.shared();
let kind = store::log_kind(&shared.db(), log_id)?;
if state.hosts.contains_key(log_id) || kind.as_deref() == Some(KIND_HOST) {
return Err(ShelfError::Invalid(format!(
"{log_id} is a host log, not a book"
)));
}
let kind = if kind.as_deref() == Some(KIND_JOURNAL) {
KIND_JOURNAL
} else {
KIND_BOOK
};
let log = Log::open(&shared.path, log_id, &shared.checkpoint_key, &[], true)?;
let indexes = shared
.authenticated
.as_ref()
.map_or(Indexes::Defaults, |f| f(log_id));
let book = ShelfBook::open(shared.clone(), log_id, kind, log, indexes)?;
state.books.insert(log_id.to_string(), book.clone());
Ok(book)
}
pub fn books(&self) -> Result<Vec<String>, ShelfError> {
let state = self.lock();
if state.released {
return Err(ShelfError::Released);
}
let db = self.shared().db();
let mut stmt = db.prepare(
"SELECT DISTINCT book_id FROM book_records WHERE book_id NOT IN (SELECT log_id FROM shelf_logs WHERE kind = 'journal') ORDER BY book_id",
)?;
let ids = stmt.query_map([], |r| r.get(0))?;
Ok(ids.collect::<Result<_, _>>()?)
}
pub fn legacy(&self, log_id: &str) -> Result<HostLog, ShelfError> {
let mut state = self.lock();
self.host_locked(&mut state, log_id, true, false)
}
pub fn host_log(&self, log_id: &str, in_cadence: bool) -> Result<HostLog, ShelfError> {
let mut state = self.lock();
self.host_locked(&mut state, log_id, in_cadence, true)
}
pub(crate) fn host_locked(
&self,
state: &mut ShelfState,
log_id: &str,
in_cadence: bool,
provision: bool,
) -> Result<HostLog, ShelfError> {
if state.released {
return Err(ShelfError::Released);
}
if let Some(host) = state.hosts.get(log_id) {
if host.in_cadence != in_cadence {
return Err(ShelfError::Invalid(format!(
"host log {log_id} is already open {} the cadence",
if host.in_cadence { "in" } else { "outside" }
)));
}
return Ok(HostLog {
shelf: self.clone(),
core: host.clone(),
});
}
if state.books.contains_key(log_id) {
return Err(ShelfError::Invalid(format!(
"{log_id} is a book, not a host log"
)));
}
if state.cadence.as_ref().is_some_and(|(id, _)| id == log_id) {
return Err(ShelfError::Invalid(format!("{log_id} is the cadence log")));
}
let shared = self.shared();
{
let db = shared.db();
let kind = store::log_kind(&db, log_id)?;
if kind.as_deref() == Some(KIND_JOURNAL) {
return Err(ShelfError::Invalid(format!(
"{log_id} is the shelf's journal, not a host log"
)));
}
if kind.as_deref() == Some(KIND_BOOK) || store::record_count(&db, log_id)? > 0 {
return Err(ShelfError::Invalid(format!(
"{log_id} is a book, not a host log"
)));
}
}
let log = Log::open(&shared.path, log_id, &shared.checkpoint_key, &[], provision)?;
let claimed = (|| -> Result<(), ShelfError> {
let mut db = shared.db();
let tx = store::write_tx(&mut db)?;
let held = store::log_kind(&tx, log_id)?;
let known: i64 = tx.query_row(
"SELECT COUNT(*) FROM cadence_logs WHERE log_id = ?",
[log_id],
|r| r.get(0),
)?;
if !in_cadence && known > 0 {
return Err(ShelfError::Invalid(format!(
"host log {log_id} is in the cadence"
)));
}
if in_cadence && held.as_deref() == Some(KIND_HOST) && known == 0 {
return Err(ShelfError::Invalid(format!(
"host log {log_id} is outside the cadence"
)));
}
store::claim_kind(&tx, log_id, KIND_HOST)?;
if in_cadence && known == 0 {
store::mark_live(&tx, log_id)?;
}
tx.commit()?;
Ok(())
})();
if let Err(e) = claimed {
let _ = log.release();
return Err(e);
}
let core = Arc::new(HostCore {
id: log_id.to_string(),
log: Arc::new(log),
in_cadence,
});
state.hosts.insert(log_id.to_string(), core.clone());
Ok(HostLog {
shelf: self.clone(),
core,
})
}
pub fn release(&self) -> Result<(), ShelfError> {
let mut state = self.lock();
if state.released {
return Ok(());
}
state.released = true;
self.shared().closed.store(true, Ordering::SeqCst);
let mut first: Option<ShelfError> = None;
let mut keep = |r: Result<(), ShelfError>| {
if let Err(e) = r {
first.get_or_insert(e);
}
};
for book in state.books.values() {
book.0.lock().released = true;
keep(book.0.log.release());
}
for host in state.hosts.values() {
keep(host.log.release());
}
if let Some((_, log)) = &state.cadence {
keep(log.release());
}
{
let mut db = self.shared().db();
match Connection::open_in_memory() {
Ok(empty) => {
let old = std::mem::replace(&mut *db, empty);
keep(old.close().map_err(|(_, e)| e.into()));
}
Err(e) => keep(Err(e.into())),
}
}
if let Some(lock) = state.lock.take() {
keep(lock.release());
}
match first {
Some(e) => Err(e),
None => Ok(()),
}
}
}
pub struct HostLogStores {
pub log: Arc<cll::log::sqlite::SqliteStore>,
pub originals: Arc<dyn ArtifactStore + Send + Sync>,
}
#[derive(Clone)]
pub struct HostLog {
shelf: Shelf,
core: Arc<HostCore>,
}
impl HostLog {
pub fn log_id(&self) -> &str {
&self.core.id
}
pub fn in_cadence(&self) -> bool {
self.core.in_cadence
}
pub fn write<T, E>(&self, write: impl FnOnce(&HostLogStores) -> Result<T, E>) -> Result<T, E>
where
E: From<ShelfError>,
{
let state = self.shelf.lock();
if state.released {
return Err(ShelfError::Released.into());
}
if self.core.in_cadence {
let mut db = self.shelf.shared().db();
let tx = store::write_tx(&mut db)?;
store::mark_live(&tx, &self.core.id)?;
tx.commit().map_err(ShelfError::from)?;
}
let _log = self.core.log.mu.lock().unwrap_or_else(|p| p.into_inner());
let result = write(&self.stores_unchecked());
drop(state);
result
}
pub fn stores(&self) -> Result<HostLogStores, ShelfError> {
if self.core.in_cadence {
return Err(ShelfError::Invalid(format!(
"host log {} is in the cadence; write to it through HostLog::write",
self.core.id
)));
}
if self.shelf.lock().released {
return Err(ShelfError::Released);
}
Ok(self.stores_unchecked())
}
fn stores_unchecked(&self) -> HostLogStores {
HostLogStores {
log: self.core.log.store.clone(),
originals: self.shelf.shared().originals.clone(),
}
}
}