xs/lib.rs
1//! `cross-stream` (`xs`) is an embeddable, local-first event stream store for
2//! event sourcing in Rust applications.
3//!
4//! The `xs` binary exposes this as a CLI and an HTTP/socket API, but this crate
5//! is the library you embed directly. It was built to back a Tauri clipboard
6//! manager: one append-only stream of events, durable on disk, with live
7//! subscriptions that drive the UI.
8//!
9//! The package is `cross-stream`; the crate is imported as `xs`:
10//!
11//! ```toml
12//! [dependencies]
13//! cross-stream = "0.13"
14//! ```
15//!
16//! # Model
17//!
18//! - A [`Store`] is an append-only log of [`Frame`]s, ordered by time-sortable
19//! [scru128](https://github.com/scru128/spec) [`Scru128Id`]s. It is [`Clone`],
20//! and clones share the same underlying database, so hand copies to wherever
21//! you need them.
22//! - A [`Frame`] is metadata: a [`topic`](Frame::topic), optional JSON
23//! [`meta`](Frame::meta), an optional content [`hash`](Frame::hash), and a
24//! [`TTL`]. Payload bytes live in a content-addressed store (CAS); the frame
25//! references them by hash. Small structured data can ride along in `meta`;
26//! larger blobs go in the CAS.
27//! - [`Store::append`] writes a frame and broadcasts it to live readers.
28//! - [`Store::read`] replays history and, with [`FollowOption::On`], keeps
29//! streaming new appends as they happen.
30//!
31//! # Quick start
32//!
33//! ```no_run
34//! use xs::{Store, Frame, ReadOptions, FollowOption};
35//!
36//! # async fn run() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
37//! // Open (or create) a store backed by a directory on disk.
38//! let store = Store::new("./clipboard-store".into())?;
39//!
40//! // Write the payload to the CAS, then append a frame that references it.
41//! let hash = store.cas_insert("hello clipboard").await?;
42//! store.append(
43//! Frame::builder("clip.add")
44//! .hash(hash)
45//! .meta(serde_json::json!({ "source": "keyboard" }))
46//! .build(),
47//! )?;
48//!
49//! // Replay history, then follow live appends to drive a UI.
50//! let mut rx = store.read(ReadOptions::builder().follow(FollowOption::On).build());
51//! while let Some(frame) = rx.recv().await {
52//! println!("{} {}", frame.id, frame.topic);
53//! }
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! # Where to look
59//!
60//! - [`store`] is the embedding surface: [`Store`], [`Frame`], [`ReadOptions`],
61//! [`FollowOption`], [`TTL`], [`Fsync`], [`StoreOptions`].
62//! - [`error`] holds the shared [`Error`] type and the
63//! [`NotFound`](error::NotFound) marker.
64//! - The remaining modules ([`api`], [`client`], [`listener`], [`processor`],
65//! [`nu`]) implement the server, the client, and the scripting runtime that
66//! the `xs` binary is built from.
67
68/// HTTP and unix-socket server: serve a [`Store`] over the wire.
69pub mod api;
70/// Client for talking to a running `xs` server.
71pub mod client;
72/// Shared error types: the boxed [`Error`](error::Error) and [`NotFound`](error::NotFound).
73pub mod error;
74/// Connection listeners (unix socket, TCP, TLS, iroh) used by the server.
75pub mod listener;
76/// Embedded Nushell runtime used to evaluate handler and generator scripts.
77pub mod nu;
78/// Background processors that run Nushell handlers against the stream.
79pub mod processor;
80/// Helpers for inspecting and constructing scru128 IDs.
81pub mod scru128;
82/// The event stream store: the core embedding API.
83pub mod store;
84/// Tracing/log setup helpers.
85pub mod trace;
86
87pub use error::Error;
88pub use store::{FollowOption, Frame, Fsync, ReadOptions, Store, StoreError, StoreOptions, TTL};
89
90/// Time-sortable, 128-bit unique identifier used to order [`Frame`]s.
91///
92/// Re-exported from the [`scru128`](https://crates.io/crates/scru128) crate.
93pub use ::scru128::Scru128Id;