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
51//!     .read(ReadOptions::builder().follow(FollowOption::On).build())
52//!     .await;
53//! while let Some(frame) = rx.recv().await {
54//!     println!("{} {}", frame.id, frame.topic);
55//! }
56//! # Ok(())
57//! # }
58//! ```
59//!
60//! # Where to look
61//!
62//! - [`store`] is the embedding surface: [`Store`], [`Frame`], [`ReadOptions`],
63//!   [`FollowOption`], [`TTL`].
64//! - [`error`] holds the shared [`Error`] type and the
65//!   [`NotFound`](error::NotFound) marker.
66//! - The remaining modules ([`api`], [`client`], [`listener`], [`processor`],
67//!   [`nu`]) implement the server, the client, and the scripting runtime that
68//!   the `xs` binary is built from.
69
70/// HTTP and unix-socket server: serve a [`Store`] over the wire.
71pub mod api;
72/// Client for talking to a running `xs` server.
73pub mod client;
74/// Shared error types: the boxed [`Error`](error::Error) and [`NotFound`](error::NotFound).
75pub mod error;
76/// Connection listeners (unix socket, TCP, TLS, iroh) used by the server.
77pub mod listener;
78/// Embedded Nushell runtime used to evaluate handler and generator scripts.
79pub mod nu;
80/// Background processors that run Nushell handlers against the stream.
81pub mod processor;
82/// Helpers for inspecting and constructing scru128 IDs.
83pub mod scru128;
84/// The event stream store: the core embedding API.
85pub mod store;
86/// Tracing/log setup helpers.
87pub mod trace;
88
89pub use error::Error;
90pub use store::{FollowOption, Frame, ReadOptions, Store, StoreError, TTL};
91
92/// Time-sortable, 128-bit unique identifier used to order [`Frame`]s.
93///
94/// Re-exported from the [`scru128`](https://crates.io/crates/scru128) crate.
95pub use ::scru128::Scru128Id;
xs/lib.rs

xs/
lib.rs
