Struct PackWriter 

pub struct PackWriter { /* private fields */ }

Builds a packfile, enforcing entry/payload caps and streaming each pushed entry’s frame directly into the final output buffer as it arrives. Self::finish only patches the header’s entry count (unknown up front from a streaming writer) and appends the trailer — it never re-copies the pushed entries into a second, same-sized buffer (issue #647).

Implementations

impl PackWriter

pub fn new() -> Self

Create an empty writer.

pub fn push_raw( &mut self, hash_of_bytes: Hash, bytes: &[u8], ) -> Result<Hash, PackError>

Append a raw object entry. bytes is the fully serialised object payload; hash_of_bytes is the BLAKE3 of those same bytes — callers usually have it on hand from the object store, so we take it explicitly to avoid an extra BLAKE3 pass over the same buffer. Takes bytes by reference (not by value): the streaming writer copies it straight into the output buffer as it’s pushed, so it never needs to own the caller’s copy (issue #647). Returns the same hash for chaining.

Applies the SPEC-PACKFILE §3.3 compression policy transparently: if bytes compresses under zstd strictly smaller on the wire (and is long enough to bother, see MIN_COMPRESS_LEN), this emits a 0x03 zstd-raw entry instead of 0x00 raw — callers never need to opt in. Either way the returned/stored identity (hash_of_bytes) is unchanged; only the wire encoding differs.

pub fn push_delta( &mut self, base_hash: &Hash, delta_stream: &[u8], ) -> Result<(), PackError>

Append a delta entry. base_hash MUST refer to an earlier raw entry in this pack OR an object already in the destination store. delta_stream MUST be a valid SPEC-DELTA stream — we don’t re-validate here (the writer is trusted), but the reader will.

Applies the same §3.3 compression policy as Self::push_raw, but ONLY to delta_stream — base_hash is always written uncompressed (SPEC-PACKFILE §3.4), so ordering/base-discovery logic never needs to decompress anything. Emits 0x04 zstd-delta when the stream compresses strictly smaller on the wire and is long enough to bother; 0x02 delta otherwise.

pub fn entry_count(&self) -> usize

Number of entries pushed so far. Useful for sizing diagnostics.

pub fn total_payload(&self) -> u64

Sum of wire payload bytes pushed so far — the quantity the writer’s own internal cap check compares against MAX_TOTAL_PAYLOAD. Measured post-compression (SPEC-PACKFILE §5): each push_raw/push_delta call adds the wire payload length, not the caller’s uncompressed input length. Callers deciding whether to seal a pack before pushing another entry can use a conservative uncompressed-length estimate against this value — the actual wire cost is never more than that estimate, since compression is only ever applied when it’s strictly smaller (see maybe_compress).

pub fn finish(self) -> Result<Vec<u8>, PackError>

Serialise the pack: header + entries + trailer. Entries are already in self.buf (streamed in by push_raw/push_delta); finish patches the header’s version (SPEC-PACKFILE §1: v2 iff at least one entry ended up compressed, v1 otherwise) and entry_count, then appends the trailer, BLAKE3(everything_before_trailer). The whole pack’s BLAKE3 is the on-disk pack key — see pack_key.

Trait Implementations

impl Debug for PackWriter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PackWriter

fn default() -> Self

Returns the “default value” for a type.