actionqueue_storage/lib.rs
1#![forbid(unsafe_code)]
2//! Storage utilities and abstractions for the ActionQueue system.
3//!
4//! This crate provides storage facilities for the ActionQueue system, including
5//! Write-Ahead Log (WAL) persistence, snapshot management, and recovery replay.
6//!
7//! # Overview
8//!
9//! The storage crate defines the persistence layer for the ActionQueue system:
10//!
11//! - [`mutation`] - Storage-owned WAL-first mutation authority
12//! - [`wal`] - Write-Ahead Log for event persistence
13//! - [`snapshot`] - State snapshots for recovery acceleration
14//! - [`recovery`] - WAL replay and state reconstruction
15//!
16//! # Example
17//!
18//! ```
19//! use actionqueue_core::ids::TaskId;
20//! use actionqueue_core::mutation::{
21//! DurabilityPolicy, MutationAuthority, MutationCommand, TaskCreateCommand,
22//! };
23//! use actionqueue_core::task::constraints::TaskConstraints;
24//! use actionqueue_core::task::metadata::TaskMetadata;
25//! use actionqueue_core::task::run_policy::RunPolicy;
26//! use actionqueue_core::task::task_spec::{TaskPayload, TaskSpec};
27//! use actionqueue_storage::mutation::StorageMutationAuthority;
28//! use actionqueue_storage::recovery::reducer::ReplayReducer;
29//! use actionqueue_storage::wal::fs_writer::WalFsWriter;
30//!
31//! // Build a unique temporary WAL path for this process.
32//! let unique = std::time::SystemTime::now()
33//! .duration_since(std::time::UNIX_EPOCH)
34//! .expect("clock should be after unix epoch")
35//! .as_nanos();
36//! let wal_path = std::env::temp_dir().join(format!("actionqueue-storage-example-{unique}.wal"));
37//!
38//! // Authority lane owns durable ordering: validate -> append -> durability -> apply.
39//! let wal_writer = WalFsWriter::new(wal_path.clone()).expect("failed to create WAL writer");
40//! let projection = ReplayReducer::new();
41//! let mut authority = StorageMutationAuthority::new(wal_writer, projection);
42//!
43//! let task_id = TaskId::new();
44//! let task_spec = TaskSpec::new(
45//! task_id,
46//! TaskPayload::with_content_type(b"example-payload".to_vec(), "application/octet-stream"),
47//! RunPolicy::Once,
48//! TaskConstraints::default(),
49//! TaskMetadata::default(),
50//! )
51//! .expect("task spec should be valid");
52//!
53//! authority
54//! .submit_command(
55//! MutationCommand::TaskCreate(TaskCreateCommand::new(1, task_spec, 0)),
56//! DurabilityPolicy::Immediate,
57//! )
58//! .expect("authority command should succeed");
59//!
60//! # // Clean up
61//! # let _ = std::fs::remove_file(wal_path);
62//! ```
63
64pub mod mutation;
65pub mod recovery;
66pub mod snapshot;
67pub mod wal;