tephra 0.4.0

//! A DCB-compliant, immutable event store with global ordering.
//!
//! Tephra is a Dynamic Consistency Boundary (DCB) event store. Instead of a static consistency
//! boundary baked into an aggregate, the boundary is derived per decision from a [`Query`].
//! Events carry an [`EventType`] plus a set of [`Tags`], so one event can belong to several
//! entities at once, and a decision reads exactly the events it depends on and guards exactly
//! those on append (an [`AppendCondition`]).
//!
//! This crate is the embedded engine: the durable log, the single writer, the index, and the
//! read paths. Use it directly in-process, or reach it over the network with the
//! [`tephra-server`](https://crates.io/crates/tephra-server) TCP server and the
//! [`tephra-client`](https://crates.io/crates/tephra-client) client.
//!
//! # Design
//!
//! The log is the source of truth and everything else is derived. Data is written once, never
//! updated and never deleted, keyed by a dense monotonic [`Position`] assigned by the single
//! writer. Indexes need no write-ahead log and no fsync on the write path, because they can be
//! rebuilt by replaying the log. The `ARCHITECTURE.md` document in the repository records the
//! full rationale and the alternatives that were rejected.
//!
//! # Example
//!
//! ```no_run
//! use tephra::{
//!     AppendCondition, Event, EventType, Position, Query, QueryItem, SegmentConfig,
//!     SegmentSet, Tag, Tags, WriteCoordinator, WriterConfig,
//! };
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Open (or create) a log directory and start the single-writer coordinator.
//! let set = SegmentSet::open("tephra-data", SegmentConfig::new(256 * 1024 * 1024))?;
//! let (coordinator, handle) = WriteCoordinator::start(set, WriterConfig::default())?;
//!
//! // Build a packed event, then append it guarded so it fails if course:c1 already exists.
//! let ty = EventType::new("CourseOpened")?;
//! let tags = Tags::new([Tag::new("course:c1")?])?;
//! let event = Event::new(&ty, &tags, br#"{"course":"c1","seats":30}"#)?;
//! let guard = AppendCondition::new(Query::item(QueryItem::with_tags(
//!     Tags::new([Tag::new("course:c1")?])?,
//! )));
//! handle.append(vec![event], Some(guard))?;
//!
//! // Reads run on the caller's thread over a snapshot published at each commit. `read` returns
//! // a lending iterator, so it is consumed with `while let`, not a `for` loop.
//! let query = Query::item(QueryItem::with_tags(Tags::new([Tag::new("course:c1")?])?));
//! let mut reads = handle.read(&query, Position::ZERO, None);
//! while let Some(item) = reads.next() {
//!     let seq = item?;
//!     println!("{} {}", seq.position, seq.event.event_type());
//! }
//!
//! // Shutdown joins the writer thread and flushes cleanly.
//! coordinator.shutdown();
//! # Ok(())
//! # }
//! ```
//!
//! # One writer per directory
//!
//! A data directory takes one writer at a time, and that is now enforced: opening a
//! [`SegmentSet`] read-write takes a lock on a `LOCK` file in the directory and holds it for
//! the set's lifetime. A second writer, in this process or any other, is refused with
//! [`LogError::Locked`](log::set::LogError::Locked) rather than quietly corrupting the log.
//! The kernel releases it however the process exits, so a leftover `LOCK` file blocks
//! nothing, and because it is a POSIX record lock rather than a descriptor-based one, a
//! forked child does not inherit it.
//!
//! # Reading from a second process
//!
//! [`Follower`] opens the same directory read-only and tracks a live writer, without
//! creating, deleting or writing anything and without taking any lock. It hands out an
//! ordinary [`ReadHandle`], so queries, backward reads and subscriptions all work as they do
//! against a writer.
//!
//! ```no_run
//! use std::sync::Arc;
//! use std::time::Duration;
//! use tephra::{Follower, FollowerConfig, SegmentConfig};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let follower = Follower::open(
//!     "tephra-data",
//!     FollowerConfig::new(SegmentConfig::new(256 * 1024 * 1024)),
//! )?;
//!
//! // Advance to whatever the writer has committed, then read at that tip.
//! let tip = follower.refresh()?;
//! println!("following up to {tip}");
//!
//! // Or let a background thread advance it, which is what makes subscriptions work.
//! let follower = Arc::new(follower);
//! let _poller = follower.poll_every(Duration::from_millis(10));
//! # Ok(())
//! # }
//! ```
//!
//! What a follower sees is always a committed prefix: gap-free, duplicate-free, and only
//! growing. It is not a durability oracle, though, and it lags. See the [`follow`] module
//! docs for the full argument and the caveats before relying on one.

pub mod event;
pub mod follow;
pub mod index;
pub mod log;
pub mod query;
pub mod read;
pub mod writer;

pub use event::{Event, EventRef};
pub use follow::{Follower, FollowerConfig, FollowerError, FollowerPoller, PollerHealth};
pub use log::set::{PositionRange, Refreshed, SegmentConfig, SegmentSet};
pub use query::Matches;
#[cfg(feature = "async")]
pub use read::pool::{ReadPool, ReadPoolConfig, ReadStream};
pub use read::{
    DEFAULT_MAX_BATCH_EVENTS, ReadConfig, ReadError, ReadHandle, Subscription, WaitOutcome,
};
pub use tephra_types::{
    AppendCondition, EventType, MAX_NAME_LEN, NameError, Position, Query, QueryItem, Tag, Tags,
    TagsError,
};
pub use writer::{
    AppendError, ConflictClause, ConflictSite, WriteCoordinator, WriteHandle, WriterConfig,
};

/// The crate README and the workspace README, compiled as doctests so their code samples
/// cannot drift from the API. These items exist only during doctest builds (`cfg(doctest)`),
/// so they never appear in the published documentation.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct CrateReadme;

#[cfg(doctest)]
#[doc = include_str!("../../../README.md")]
struct WorkspaceReadme;