Struct HashtreeStore 

pub struct HashtreeStore { /* private fields */ }

Implementations

impl HashtreeStore

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_with_chunk_size<P: AsRef<Path>>( &self, file_path: P, chunk_size: Option<usize>, ) -> Result<String>

pub fn upload_file_with_chunk_size_and_progress<P: AsRef<Path>>( &self, file_path: P, chunk_size: Option<usize>, progress: &AddProgress, ) -> Result<String>

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 and ignores common OS junk files 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_dir_with_options_and_chunk_size<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, chunk_size: Option<usize>, ) -> Result<String>

pub fn upload_dir_with_options_and_chunk_size_and_progress<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, chunk_size: Option<usize>, progress: &AddProgress, ) -> Result<String>

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_file_encrypted_with_chunk_size<P: AsRef<Path>>( &self, file_path: P, chunk_size: Option<usize>, ) -> Result<String>

pub fn upload_file_encrypted_with_chunk_size_and_progress<P: AsRef<Path>>( &self, file_path: P, chunk_size: Option<usize>, progress: &AddProgress, ) -> Result<String>

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

Upload a directory with CHK encryption, returns CID Respects .gitignore and ignores common OS junk files 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 upload_dir_encrypted_with_options_and_chunk_size<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, chunk_size: Option<usize>, ) -> Result<String>

pub fn upload_dir_encrypted_with_options_and_chunk_size_and_progress<P: AsRef<Path>>( &self, dir_path: P, respect_gitignore: bool, chunk_size: Option<usize>, progress: &AddProgress, ) -> Result<String>

impl HashtreeStore

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

pub fn compact_lmdb_environments( &self, env_dirs: &[PathBuf], keep_backup: bool, ) -> Result<Vec<CompactResult>>

impl HashtreeStore

pub fn make_room_for_cached_blob(&self, incoming_bytes: u64) -> Result<u64>

pub fn enforce_cached_blob_budget_after_insert( &self, inserted_bytes: u64, ) -> Result<u64>

pub fn make_room_for_durable_blob(&self, incoming_bytes: u64) -> Result<u64>

pub fn enforce_durable_blob_budget_after_insert( &self, inserted_bytes: u64, ) -> Result<u64>

pub fn relieve_cached_blob_write_pressure( &self, incoming_bytes: u64, ) -> Result<u64>

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 owned_blob_stats(&self) -> Result<Vec<OwnedBlobStats>>

pub fn tree_index_limits(&self) -> TreeIndexLimits

Bounds complete-DAG indexing by both the configured storage budget and an absolute traversal-node ceiling. A zero storage budget means the raw store is unbounded, but authenticated requests still retain a hard cap.

pub fn pin_and_index_tree( &self, root: &Cid, owner: &str, name: Option<&str>, priority: u8, limits: TreeIndexLimits, ) -> Result<PinTreeResult, PinTreeError>

Validate every referenced blob, then index all descendants and pin the root in one LMDB transaction. No pin or index metadata is written if traversal, decryption, decoding, or resource validation fails.

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 get_tree_ref(&self, key: &str) -> Result<Option<Hash>>

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 access age (least recent 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

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 with_options_and_backend<P: AsRef<Path>>( path: P, s3_config: Option<&S3Config>, max_size_bytes: u64, evict_orphans: bool, backend: &StorageBackend, ) -> Result<Self>

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

Create a store for an embedded, single-process hashtree host.

The macOS app sandbox denies LMDB’s default System V semaphore locks. The embedded host owns this data directory in one process, so it uses external process isolation plus LMDB NO_LOCK for metadata and the filesystem blob backend to avoid opening a second LMDB environment.

pub fn base_path(&self) -> &Path

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 force_sync(&self) -> Result<()>

pub fn record_blob_accesses<I>(&self, hashes: I)

where I: IntoIterator<Item = Hash>,

pub fn blob_last_accessed_at(&self, hash: &Hash) -> Result<Option<u64>>

pub fn blob_last_accessed_many( &self, hashes: &[Hash], ) -> Result<Vec<(Hash, u64)>>

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 put_owned_blob_with_inserted( &self, data: &[u8], pubkey: &[u8; 32], ) -> Result<(String, bool)>

Store an owned Blossom blob under the configured durable storage limit.

pub fn put_owned_blob(&self, data: &[u8], pubkey: &[u8; 32]) -> Result<String>

pub fn put_owned_blobs_report( &self, items: &[(Hash, Vec<u8>)], pubkey: &[u8; 32], ) -> Result<PutManyReport>

Store multiple owned Blossom blobs, batching raw blob and owner-index writes.

pub fn put_owned_blobs( &self, items: &[(Hash, Vec<u8>)], pubkey: &[u8; 32], ) -> Result<usize>

Store multiple owned Blossom blobs, returning only the number of new blobs.

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

Store an opportunistically cached blob.

Unlike durable put_blob writes, this path may evict disposable orphaned blobs to make room under storage pressure. It intentionally avoids touching indexed trees, social-graph roots, explicit pins, and owned Blossom blobs.

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

pub fn put_cached_blobs_report( &self, items: &[(Hash, Vec<u8>)], ) -> Result<PutManyReport>

Store multiple opportunistically cached blobs in one raw storage batch.

pub fn put_cached_blobs(&self, items: &[(Hash, Vec<u8>)]) -> Result<usize>

Store multiple opportunistically cached blobs, returning only the number of new blobs.

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

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

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

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

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<Arc<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 add_pinned_ref(&self, key: &str) -> Result<()>

Persist a mutable published ref that should stay subscribed.

pub fn remove_pinned_ref(&self, key: &str) -> Result<bool>

Remove a mutable published ref from the live pinned set.

pub fn list_pinned_refs(&self) -> Result<Vec<String>>

List mutable published refs that should stay subscribed.

pub fn add_tracked_author(&self, npub: &str) -> Result<bool>

Persist an author whose published trees should stay mirrored.

pub fn remove_tracked_author(&self, npub: &str) -> Result<bool>

Remove an author from the continuous mirror set.

pub fn list_tracked_authors(&self) -> Result<Vec<String>>

List authors whose published trees should stay mirrored.

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

Trait Implementations

impl ContentStore for HashtreeStore

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

Get content by hex hash