Gitility.Bundle.Format (Gitility v0.4.0)

Pure encoder and strict positional parser for Gitility bundle format v1.

Opening verifies the header, EOF trailer, TOC identity, bounds, section tiling, pack/index pairing, and the complete metadata/ref grammar. Unknown metadata keys and FILE kinds remain minor-additive space, except for the reserved shallow_roots feature gate, which v1 readers refuse rather than silently misreading shallow history. Section payload hashes are intentionally deferred to Gitility.Bundle.verify/1.

Summary

Types

file_entry()

file_kind()

ref_entry()

toc()

Functions

encode_header()

Encodes the fixed bundle v1 header.

encode_toc(map)

Encodes a deterministically ordered bundle v1 table of contents.

encode_trailer(toc_offset, toc_len, arg)

Encodes the fixed bundle v1 trailer.

max_toc_len()

The format's TOC size ceiling; readers reject and writers refuse beyond it.

parse(path)

Parses and structurally validates one bundle without hashing section payloads.

Types

file_entry()

@type file_entry() :: %{
  kind: file_kind(),
  name: binary(),
  offset: non_neg_integer(),
  length: pos_integer(),
  sha256: <<_::256>>
}

file_kind()

@type file_kind() :: :pack | :idx | {:unknown, 0..255}

ref_entry()

@type ref_entry() :: %{
  name: binary(),
  target: binary(),
  kind: Gitility.Object.object_type(),
  peeled: binary() | nil
}

toc()

@type toc() :: %{
  format_major: pos_integer(),
  format_minor: non_neg_integer(),
  hash_algorithm: Gitility.OID.algorithm(),
  generation: pos_integer(),
  metadata: %{required(binary()) => binary()},
  files: [file_entry()],
  sections: [file_entry()],
  refs: [ref_entry()],
  toc_offset: non_neg_integer(),
  toc_len: non_neg_integer(),
  toc_sha256: <<_::256>>,
  file_size: non_neg_integer()
}

Functions

encode_header()

@spec encode_header() :: binary()

Encodes the fixed bundle v1 header.

encode_toc(map)

@spec encode_toc(map()) :: binary()

Encodes a deterministically ordered bundle v1 table of contents.

encode_trailer(toc_offset, toc_len, arg)

@spec encode_trailer(non_neg_integer(), non_neg_integer(), <<_::256>>) :: binary()

Encodes the fixed bundle v1 trailer.

max_toc_len()

@spec max_toc_len() :: pos_integer()

The format's TOC size ceiling; readers reject and writers refuse beyond it.

parse(path)

@spec parse(Path.t()) :: {:ok, toc()} | {:error, Gitility.Error.t()}

Parses and structurally validates one bundle without hashing section payloads.