xtax_blob_storage/
lib.rs

1#![cfg_attr(docsrs, feature(doc_cfg))]
2
3//! # xtax-blob-storage
4//!
5//! > **Experimental** blob storage abstraction for Rust with filesystem and S3
6//! > backends, streaming uploads, optional encryption, and composable layers.
7//!
8//! A compact, builder-driven blob storage abstraction. See the
9//! [crate-level README](https://github.com/cz-jcode/xtax/blob/main/crates/xtax-blob-storage/README.md)
10//! for the full rationale and comparisons.
11//!
12//! ## Status
13//!
14//! **Experimental / learning project.** Not production-ready.
15//!
16//! ## Architecture
17//!
18//! ```text
19//!  BlobStore trait  ←  everyone implements this
20//!       ↑
21//!  ┌────┴──────────────┐
22//!  │  FsBlobStore      │  filesystem backend (feature = "fs")
23//!  │  S3BlobStore      │  S3/Garage backend (feature = "s3")
24//!  └────┬──────────────┘
25//!       │
26//!  ┌────┴───────────────────────────────┐
27//!  │  PrefixBlobStore                   │  key prefix manipulation
28//!  │  EncryptedBlobStore                │  encryption
29//!  │  BlobCleanup                       │  cleanup by predicate
30//!  └────┬───────────────────────────────┘
31//!       │
32//!  BlobStore trait  ←  still the same trait, fully composable
33//! ```
34//!
35//! ## Quick start
36//!
37//! ```rust,no_run
38//! use xtax_blob_storage::{BlobStoreBuilder, BlobInput};
39//!
40//! # #[cfg(feature = "fs")]
41//! # #[tokio::main]
42//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
43//! # #[cfg(feature = "fs")]
44//! # {
45//! let store = BlobStoreBuilder::new()
46//!     .with_fs("/tmp/data")
47//!     .with_prefix("my-app/")
48//!     .build()
49//!     .await?;
50//!
51//! use tokio::io::AsyncReadExt;
52//!
53//! store.put(vec![BlobInput::new("hello.txt", b"data".as_slice())]).await?;
54//!
55//! let mut reader = store.get("hello.txt").await?;
56//! let mut buf = String::new();
57//! reader.read_to_string(&mut buf).await?;
58//! assert_eq!(buf, "data");
59//! # Ok(())
60//! # }
61//! # }
62//! # #[cfg(not(feature = "fs"))]
63//! # fn main() {}
64//! ```
65//!
66//! ## AI contribution note
67//!
68//! This library was developed with LLM assistance under continuous human supervision.
69//!
70
71// ---------------------------------------------------------------------------
72// Internal modules (private) — types are re-exported below
73// ---------------------------------------------------------------------------
74
75mod blob_store;
76mod builder;
77mod cleanup;
78mod encrypt;
79mod error;
80mod list_filter;
81mod prefix;
82mod types;
83pub mod validate;
84mod visitor;
85
86// ---------------------------------------------------------------------------
87// Backend modules — public so users can construct them directly if needed
88// ---------------------------------------------------------------------------
89
90/// Filesystem-backed blob store.
91///
92/// Blobs are stored as individual files under a root directory. Keys
93/// containing `/` are mapped to nested directories — identical behaviour
94/// to S3.
95///
96/// For full documentation see the
97/// [Backends guide](https://github.com/cz-jcode/xtax/blob/main/crates/xtax-blob-storage/docs/backends.md).
98///
99/// *Requires the `fs` feature (enabled by default).*
100#[cfg(feature = "fs")]
101#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
102pub mod fs;
103
104/// S3-compatible blob store.
105///
106/// Works with AWS S3, Garage, MinIO, and any S3-compatible service.
107/// Supports multipart uploads with configurable threshold.
108///
109/// For full documentation see the
110/// [Backends guide](https://github.com/cz-jcode/xtax/blob/main/crates/xtax-blob-storage/docs/backends.md).
111///
112/// *Requires the `s3` feature (opt-in).*
113#[cfg(feature = "s3")]
114#[cfg_attr(docsrs, doc(cfg(feature = "s3")))]
115pub mod s3;
116
117// ---------------------------------------------------------------------------
118// Re-exports — the public API surface
119// ---------------------------------------------------------------------------
120
121pub use blob_store::BlobStore;
122pub use builder::{
123    BackgroundCancellation, BackgroundContext, BackgroundStrategy, BlobStoreBuilder,
124    MaintenanceTrigger, Manual, OnStart, Periodic,
125};
126pub use cleanup::{BlobCleanup, CleanupPredicate};
127pub use encrypt::{
128    EncryptionError, EncryptionProvider, EncryptionResult, store::EncryptedBlobStore,
129};
130pub use error::{BatchError, BlobStorageError, KeyError, PerKeyError, Result};
131pub use list_filter::{ListFilter, NotFilter, PrefixFilter, SuffixFilter};
132pub use types::{BlobInput, BlobMeta, CleanupResult, KEY_SEPARATOR, PutResult, RekeyResult};
133pub use validate::validate_blob_key;
134pub use visitor::BlobVisitor;
xtax_blob_storage/lib.rs

xtax_blob_storage/
lib.rs
