Skip to main content

Module read

git_remote_object_store::packchain

Module read 

Source
Expand description

Direct file access against a packchain remote (issue #65).

read_blob is the differentiated value-add of the packchain engine: a caller fetches a single file at a ref’s tip without cloning, materialising a working tree, or invoking git. The lookup walks the on-bucket artefacts the Phase 2 push wrote:

  1. chain.json to verify the ref exists.
  2. path-index.json to resolve path → blob SHA at tip.
  3. Each segment’s .idx (newest-first) to locate the blob’s pack entry.
  4. A ranged GET against the matching .pack to fetch the entry bytes, zlib-decompressed (and delta-applied, if applicable).

The pack-index parses are amortised across calls via PackIndexCache, a byte-bounded LRU keyed by (prefix, content-sha). Single-shot callers can pass &PackIndexCache::default() and let the cache GC at drop.

§Delta resolution

Pack entries may be deltas against a base elsewhere in the chain. OFS_DELTA resolves within the same pack via a relative back-offset; REF_DELTA resolves to a SHA which may live in any pack in the chain. The walker recurses, capped at MAX_DELTA_DEPTH (matching git’s own limit) so a corrupted chain with a delta cycle aborts cleanly instead of looping forever.

§What this module does not do

  • No on-disk cache: indices live in memory only. CI agents that want cross-process amortisation should layer their own.
  • No directory listings: read_blob is single-file. The nested-tree shape supports listing cleanly, but it’s a separate API and out of scope for issue #65.

Structs§

PackIndexCache
In-process LRU cache of decoded pack indices keyed by (prefix, content-sha).

Constants§

DEFAULT_CACHE_CAPACITY_BYTES
Default in-memory budget for PackIndexCache (64 MiB), matching the cap the issue #65 plan calls out. Covers a chain of dozens of large packs without thrashing.
MAX_DELTA_DEPTH
Hard cap on delta-chain depth, matching git’s own pack.deltaCacheLimit-adjacent recursion limit. A correctly built chain won’t approach this; tripping the cap means the pack is corrupted (a cycle) or pathologically deep, and either way stopping is the right call.

Functions§

read_blob
Read the contents of path at ref_name’s tip from a packchain remote.