Struct HashtreeStore 

pub struct HashtreeStore { /* private fields */ }

Implementations

impl HashtreeStore

pub fn new<P: AsRef<Path>>(path: P) -> Result<Self>

Create a new store with the configured local storage limit.

pub fn new_with_backend<P: AsRef<Path>>( path: P, backend: StorageBackend, max_size_bytes: u64, ) -> Result<Self>

Create a new store with an explicit local backend and size limit.

pub fn with_s3<P: AsRef<Path>>( path: P, s3_config: Option<&S3Config>, ) -> Result<Self>

Create a new store with optional S3 backend and the configured local storage limit.

pub fn with_options<P: AsRef<Path>>( path: P, s3_config: Option<&S3Config>, max_size_bytes: u64, ) -> Result<Self>

Create a new store with optional S3 backend and custom size limit.

The raw local blob backend remains unbounded. HashtreeStore enforces max_size_bytes at the tree-management layer so eviction can honor pins, orphan handling, and local-only eviction when S3 is used as archive.

pub fn router(&self) -> &StorageRouter

Get the storage router

pub fn store_arc(&self) -> Arc<StorageRouter>

Get the storage router as Arc (for use with HashTree which needs Arc) All writes through this go to both LMDB and S3

pub fn upload_file<P: AsRef<Path>>(&self, file_path: P) -> Result<String>

Upload a file as raw plaintext and return its CID, with auto-pin

pub fn upload_file_no_pin<P: AsRef<Path>>(&self, file_path: P) -> Result<String>

Upload a file without pinning (for blossom uploads that can be evicted)

pub fn upload_file_stream<R: Read, F>( &self, reader: R, _file_name: impl Into<String>, callback: F, ) -> Result<String>

where F: FnMut(&str),

Upload a file from a stream with progress callbacks

pub fn upload_dir<P: AsRef<Path>>(&self, dir_path: P) -> Result<String>

Upload a directory and return its root hash (hex) Respects .gitignore by default

pub fn upload_dir_with_options<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, ) -> Result<String>

Upload a directory with options as raw plaintext (no CHK encryption)

pub fn upload_file_encrypted<P: AsRef<Path>>( &self, file_path: P, ) -> Result<String>

Upload a file with CHK encryption, returns CID in format “hash:key”

pub fn upload_dir_encrypted<P: AsRef<Path>>( &self, dir_path: P, ) -> Result<String>

Upload a directory with CHK encryption, returns CID Respects .gitignore by default

pub fn upload_dir_encrypted_with_options<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, ) -> Result<String>

Upload a directory with CHK encryption and options Returns CID as “hash:key” format for encrypted directories

pub fn get_tree_node(&self, hash: &[u8; 32]) -> Result<Option<TreeNode>>

Get tree node by hash (raw bytes)

pub fn put_blob(&self, data: &[u8]) -> Result<String>

Store a raw blob, returns SHA256 hash as hex.

pub fn get_blob(&self, hash: &[u8; 32]) -> Result<Option<Vec<u8>>>

Get a raw blob by SHA256 hash (raw bytes).

pub fn blob_exists(&self, hash: &[u8; 32]) -> Result<bool>

Check if a blob exists by SHA256 hash (raw bytes).

pub fn set_blob_owner(&self, sha256: &[u8; 32], pubkey: &[u8; 32]) -> Result<()>

Add an owner (pubkey) to a blob for Blossom protocol Multiple users can own the same blob - it’s only deleted when all owners remove it

pub fn is_blob_owner( &self, sha256: &[u8; 32], pubkey: &[u8; 32], ) -> Result<bool>

Check if a pubkey owns a blob

pub fn get_blob_owners(&self, sha256: &[u8; 32]) -> Result<Vec<[u8; 32]>>

Get all owners (pubkeys) of a blob via prefix scan (returns raw bytes)

pub fn blob_has_owners(&self, sha256: &[u8; 32]) -> Result<bool>

Check if blob has any owners

pub fn get_blob_owner(&self, sha256: &[u8; 32]) -> Result<Option<[u8; 32]>>

Get the first owner (pubkey) of a blob (for backwards compatibility)

pub fn delete_blossom_blob( &self, sha256: &[u8; 32], pubkey: &[u8; 32], ) -> Result<bool>

Remove a user’s ownership of a blossom blob Only deletes the actual blob when no owners remain Returns true if the blob was actually deleted (no owners left)

pub fn list_blobs_by_pubkey( &self, pubkey: &[u8; 32], ) -> Result<Vec<BlobDescriptor>>

List all blobs owned by a pubkey (for Blossom /list endpoint)

pub fn get_chunk(&self, hash: &[u8; 32]) -> Result<Option<Vec<u8>>>

Get a single chunk/blob by hash (raw bytes)

pub fn get_file(&self, hash: &[u8; 32]) -> Result<Option<Vec<u8>>>

Get file content by hash (raw bytes) Returns raw bytes (caller handles decryption if needed)

pub fn get_file_by_cid(&self, cid: &Cid) -> Result<Option<Vec<u8>>>

Get file content by Cid (hash + optional decryption key as raw bytes) Handles decryption automatically if key is present

pub fn write_file_by_cid_to_writer<W: Write>( &self, cid: &Cid, writer: &mut W, ) -> Result<u64>

Stream file content identified by Cid into a writer without buffering full file in memory.

pub fn write_file_by_cid<P: AsRef<Path>>( &self, cid: &Cid, output_path: P, ) -> Result<u64>

Stream file content identified by Cid directly into a destination path.

pub fn write_file<P: AsRef<Path>>( &self, hash: &[u8; 32], output_path: P, ) -> Result<u64>

Stream a public (unencrypted) file by hash directly into a destination path.

pub fn resolve_path(&self, cid: &Cid, path: &str) -> Result<Option<Cid>>

Resolve a path within a tree (returns Cid with key if encrypted)

pub fn get_file_chunk_metadata( &self, hash: &[u8; 32], ) -> Result<Option<FileChunkMetadata>>

Get chunk metadata for a file (chunk list, sizes, total size)

pub fn get_file_range( &self, hash: &[u8; 32], start: u64, end: Option<u64>, ) -> Result<Option<(Vec<u8>, u64)>>

Get byte range from file

pub fn stream_file_range_chunks_owned( self: Arc<Self>, hash: &[u8; 32], start: u64, end: u64, ) -> Result<Option<FileRangeChunksOwned>>

Stream file range as chunks using Arc for async/Send contexts

pub fn get_directory_listing( &self, hash: &[u8; 32], ) -> Result<Option<DirectoryListing>>

Get directory structure by hash (raw bytes)

pub fn get_directory_listing_by_cid( &self, cid: &Cid, ) -> Result<Option<DirectoryListing>>

Get directory structure by CID, supporting encrypted directories.

pub fn pin(&self, hash: &[u8; 32]) -> Result<()>

Pin a hash (prevent garbage collection)

pub fn unpin(&self, hash: &[u8; 32]) -> Result<()>

Unpin a hash (allow garbage collection)

pub fn is_pinned(&self, hash: &[u8; 32]) -> Result<bool>

Check if hash is pinned

pub fn list_pins_raw(&self) -> Result<Vec<[u8; 32]>>

List all pinned hashes (raw bytes)

pub fn list_pins_with_names(&self) -> Result<Vec<PinnedItem>>

List all pinned hashes with names

pub fn index_tree( &self, root_hash: &Hash, owner: &str, name: Option<&str>, priority: u8, ref_key: Option<&str>, ) -> Result<()>

Index a tree after sync - tracks all blobs in the tree for eviction

If ref_key is provided (e.g. “npub…/name”), it will replace any existing tree with that ref, allowing old versions to be evicted.

pub fn unindex_tree(&self, root_hash: &Hash) -> Result<u64>

Unindex a tree - removes blob-tree mappings and deletes orphaned blobs Returns the number of bytes freed

pub fn get_tree_meta(&self, root_hash: &Hash) -> Result<Option<TreeMeta>>

Get tree metadata

pub fn list_indexed_trees(&self) -> Result<Vec<(Hash, TreeMeta)>>

List all indexed trees

pub fn tracked_size(&self) -> Result<u64>

Get total tracked storage size (sum of all tree_meta.total_size)

pub fn evict_if_needed(&self) -> Result<u64>

Run eviction if storage is over quota Returns bytes freed

Eviction order:

1. Orphaned blobs (not in any indexed tree and not pinned)
2. Trees by priority (lowest first) and age (oldest first)

pub fn max_size_bytes(&self) -> u64

Get the maximum storage size in bytes

pub fn storage_by_priority(&self) -> Result<StorageByPriority>

Get storage usage by priority tier

pub fn get_storage_stats(&self) -> Result<StorageStats>

Get storage statistics

pub fn get_cached_root( &self, pubkey_hex: &str, tree_name: &str, ) -> Result<Option<CachedRoot>>

Get cached root for a pubkey/tree_name pair

pub fn set_cached_root( &self, pubkey_hex: &str, tree_name: &str, hash: &str, key: Option<&str>, visibility: &str, updated_at: u64, ) -> Result<()>

Set cached root for a pubkey/tree_name pair

pub fn list_cached_roots( &self, pubkey_hex: &str, ) -> Result<Vec<(String, CachedRoot)>>

List all cached roots for a pubkey

pub fn delete_cached_root( &self, pubkey_hex: &str, tree_name: &str, ) -> Result<bool>

Delete a cached root

pub fn gc(&self) -> Result<GcStats>

Garbage collect unpinned content

pub fn verify_lmdb_integrity(&self, delete: bool) -> Result<VerifyResult>

Verify LMDB blob integrity - checks that stored data matches its key hash Returns verification statistics and optionally deletes corrupted entries

pub async fn verify_r2_integrity(&self, _delete: bool) -> Result<VerifyResult>

Fallback for non-S3 builds

Trait Implementations

impl ContentStore for HashtreeStore

fn get(&self, hash_hex: &str) -> Result<Option<Vec<u8>>>

Get content by hex hash