Struct PackReader 

pub struct PackReader<'a> { /* private fields */ }

Implementations

impl PackReader<'static>

pub fn open( pack_path: &Path, index_path: &Path, ) -> Result<PackReader<'static>, HeddleError>

Open a pack file. mmap-backed when the pack is large enough to benefit (the same threshold the loose-blob path uses for its own mmap decision); read-into-heap otherwise.

pub fn from_bytes( pack_data: impl Into<Bytes>, index_data: impl AsRef<[u8]>, ) -> Result<PackReader<'static>, HeddleError>

impl<'a> PackReader<'a>

pub fn from_slice( pack_data: &'a [u8], index_data: impl AsRef<[u8]>, ) -> Result<PackReader<'a>, HeddleError>

pub fn list_ids(&self) -> Result<Vec<PackObjectId>, HeddleError>

List all object ids in this pack.

pub fn logical_id(&self) -> Result<PackLogicalId, HeddleError>

Compute this pack’s root-spool-scoped logical identity.

Every logical object is decoded so delta and compact-frame physical choices cannot affect the result. The visit also validates exact index membership before an identity is returned.

pub fn representation_hash(&self) -> PackRepresentationHash

Hash the exact finalized pack bytes used by this reader.

pub fn list_hashes(&self) -> Result<Vec<ContentHash>, HeddleError>

pub fn has_object(&self, id: &PackObjectId) -> Result<bool, HeddleError>

pub fn encoded_payload_bytes( &self, obj_type: ObjectType, ) -> Result<u64, HeddleError>

Compressed payload bytes used by unique physical records of obj_type.

Shared compact frames have one record offset indexed by many logical ids, so offsets are deduplicated before bytes are counted.

pub fn visit_objects( &self, visitor: impl FnMut(PackObjectId, ObjectType, &[u8]) -> Result<(), HeddleError>, ) -> Result<(), HeddleError>

Visit every logical object while decoding each shared frame once.

The index-to-frame membership is checked exactly before objects are yielded, closing both missing-entry and stale-alias corruption paths.

pub fn copy_hosted_encoded_subset( &self, expected: &[(PackObjectId, ObjectType, u64)], ) -> Result<Option<EncodedPackSubset>, HeddleError>

Copy a validated subset of non-delta encoded entries into a standalone hosted transport pack without decoding or recompressing their bodies.

Ok(None) is a safe fallback signal: an expected object is absent, duplicated, has a different type/size, is delta encoded, or names a repository-local entry that may not cross the hosted pack boundary.

pub fn get_object( &self, id: &PackObjectId, ) -> Result<Option<(ObjectType, Vec<u8>)>, HeddleError>

Get an object from the pack.

Verifies that the tagged id at the indexed offset matches id before returning. A stale .idx file (e.g., overwritten in place after a pack rebuild) can otherwise route a request for hash A to a record physically located at hash B’s offset — same shape, different content, no error signal. This cheap 32-byte id comparison catches that without paying a full content-hash recompute on every read; corruption strictly inside the record body is a separate failure mode surfaced via the consumer-side hash verify (see FsStore::loose_blob_path for the blob equivalent).

pub fn get_hashed_object( &self, hash: &ContentHash, ) -> Result<Option<(ObjectType, Vec<u8>)>, HeddleError>

pub fn get_hashed_object_type( &self, hash: &ContentHash, ) -> Result<Option<ObjectType>, HeddleError>

Read an object’s logical type from pack headers without reading or decoding its payload.

Delta entries inherit the type of their base, so this follows only the tagged base ids and headers until it reaches a non-delta entry. No compressed or delta payload bytes are decoded. Missing hashes return Ok(None).

pub fn get_object_bytes( &self, id: &PackObjectId, ) -> Result<Option<(ObjectType, Bytes)>, HeddleError>

Zero-copy fast path: when the entry is non-delta and stored uncompressed, returns Bytes::slice into the pack’s (mmap-backed) buffer — no allocation, no memcpy. Compressed or delta entries fall back to get_object and wrap the resulting Vec<u8> in a Bytes (one Arc, no body copy).

Use this from the hot read path. The 10 MB benchmark gap between the mount and vanilla FS at the 1 MB+ tier is the per-blob memcpy this method eliminates.

pub fn get_hashed_object_bytes( &self, hash: &ContentHash, ) -> Result<Option<(ObjectType, Bytes)>, HeddleError>

pub fn get_hashed_object_size( &self, hash: &ContentHash, ) -> Result<Option<u64>, HeddleError>

Read just the type+size header for an object without decompressing its payload. Returns Ok(None) when the object isn’t in this pack.

For non-delta entries this is one varint decode at the indexed offset — much cheaper than get_object. Delta entries fall back to a full read because their resolved size requires chasing the base; in practice deltas are rare in the directory listing hot path so the fallback is acceptable.