Crate xtax_blob_storage 

xtax-blob-storage

Experimental blob storage abstraction for Rust with filesystem and S3 backends, streaming uploads, optional encryption, and composable layers.

A compact, builder-driven blob storage abstraction. See the crate-level README for the full rationale and comparisons.

Status

Experimental / learning project. Not production-ready.

Architecture

 BlobStore trait  ←  everyone implements this
      ↑
 ┌────┴──────────────┐
 │  FsBlobStore      │  filesystem backend (feature = "fs")
 │  S3BlobStore      │  S3/Garage backend (feature = "s3")
 └────┬──────────────┘
      │
 ┌────┴───────────────────────────────┐
 │  PrefixBlobStore                   │  key prefix manipulation
 │  EncryptedBlobStore                │  encryption
 │  BlobCleanup                       │  cleanup by predicate
 └────┬───────────────────────────────┘
      │
 BlobStore trait  ←  still the same trait, fully composable

Quick start

use xtax_blob_storage::{BlobStoreBuilder, BlobInput};

let store = BlobStoreBuilder::new()
    .with_fs("/tmp/data")
    .with_prefix("my-app/")
    .build()
    .await?;

use tokio::io::AsyncReadExt;

store.put(vec![BlobInput::new("hello.txt", b"data".as_slice())]).await?;

let mut reader = store.get("hello.txt").await?;
let mut buf = String::new();
reader.read_to_string(&mut buf).await?;
assert_eq!(buf, "data");

AI contribution note

This library was developed with LLM assistance under continuous human supervision.

Re-exports

pub use validate::validate_blob_key;

Modules

fsfs

Filesystem-backed blob store.

s3s3

S3-compatible blob store.

validate

Structs

BackgroundCancellation

Read-only cancellation token for background scheduling loops.

BackgroundContext

Context provided to a BackgroundStrategy during schedule().

BatchError

Batch error — returned when at least one key in a batch operation failed.

BlobCleanup

Layer that provides cleanup functionality over a BlobStore.

BlobInput

A single blob to store — key + data stream.

BlobMeta

Metadata about a stored blob.

BlobStoreBuilder

Typestate builder for constructing a BlobStore with optional layers.

CleanupResult

Result of a cleanup operation.

EncryptedBlobStore

Transparent encryption layer over a BlobStore.

KeyError

A single failed key in a batch operation, with its categorised error.

MaintenanceTrigger

A handle that can enqueue maintenance tasks.

Manual

Strategy that only runs the task when trigger() is called.

NotFilter

Inverse of another filter.

OnStart

Strategy that runs the task once immediately.

Periodic

Strategy that runs the task immediately, then repeats periodically.

PrefixFilter

Filter blobs whose key starts with a given prefix.

PutResult

Result of a put operation.

RekeyResult

Result of a rekey operation.

SuffixFilter

Filter blobs whose key ends with a given suffix.

Enums

BlobStorageError

Blob storage error.

EncryptionError

Encryption provider — abstracts the encryption operations needed by EncryptedBlobStore.

PerKeyError

Categorised error for a single key in a batch operation.

Constants

KEY_SEPARATOR

Separator used between key components.

Traits

BackgroundStrategy

Trait for scheduling background maintenance tasks (cleanup, rekey).

BlobStore

Generic blob storage abstraction.

BlobVisitor

Pluggable visitor for streaming visit() operations.

EncryptionProvider

Encryption provider — abstracts the encryption operations needed by EncryptedBlobStore.

ListFilter

Pluggable filter for list() operations.

Type Aliases

CleanupPredicate

Predicate for deciding which blobs to delete during cleanup.

EncryptionResult

Encryption provider — abstracts the encryption operations needed by EncryptedBlobStore.

Result