hyperi_rustlib/spool/
mod.rs

1// Project:   hyperi-rustlib
2// File:      src/spool/mod.rs
3// Purpose:   Disk-backed async FIFO queue with optional compression
4// Language:  Rust
5//
6// License:   BUSL-1.1
7// Copyright: (c) 2026 HYPERI PTY LIMITED
8
9//! Disk-backed async FIFO queue with optional zstd compression.
10//!
11//! This module provides a persistent queue for spooling data to disk,
12//! useful for buffering data when downstream systems are unavailable
13//! or for implementing store-and-forward patterns.
14//!
15//! Built on [yaque](https://crates.io/crates/yaque), a fast, async,
16//! persistent queue with transactional semantics.
17//!
18//! ## Features
19//!
20//! - Persistent storage survives restarts
21//! - Transactional writes (crash-safe)
22//! - Optional zstd compression for reduced disk usage
23//! - Configurable size limits
24//! - Async-native API
25//!
26//! ## Example
27//!
28//! ```rust,no_run
29//! use hyperi_rustlib::spool::{Spool, SpoolConfig};
30//!
31//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
32//! let config = SpoolConfig {
33//!     path: "/tmp/my-spool".into(),
34//!     compress: true,
35//!     ..Default::default()
36//! };
37//!
38//! let mut spool = Spool::open(config).await?;
39//!
40//! // Add items to the queue
41//! spool.push(b"first message").await?;
42//! spool.push(b"second message").await?;
43//!
44//! // Process items (FIFO order)
45//! while let Some(data) = spool.pop_front().await? {
46//!     println!("Processing: {:?}", data);
47//! }
48//! # Ok(())
49//! # }
50//! ```
51
52mod config;
53mod error;
54mod queue;
55
56pub use config::SpoolConfig;
57pub use error::SpoolError;
58pub use queue::Spool;
59
60/// Result type for spool operations.
61pub type Result<T> = std::result::Result<T, SpoolError>;
hyperi_rustlib/spool/mod.rs

hyperi_rustlib/spool/
mod.rs
