Module car 

CARv1: the file a repository is handed over as.

A CAR file is a header and then a pile of blocks, each one prefixed by its own length. It carries no index, no ordering rule and no compression — it is a way of putting content-addressed blocks in a stream and nothing more, and what makes it usable is that every block names itself, so a reader can start from the root the header declares and follow links.

The framing, in full

varint(len(header))  header                 header is DAG-CBOR
varint(len(cid) + len(block))  cid  block   repeated, in any order

The varint is unsigned LEB128, the same one multiformats uses everywhere else. The header is {"roots": [<link>], "version": 1} — version is the CAR format’s own version and has nothing to do with the repository version in a commit, which is 3. Two different numbers called version in one file is a genuine trap and the reason this is spelled out here.

Reading one back

read is the other direction, and it arrived with the Merkle search tree conformance suite: the trees those vectors describe are handed over as CAR files, so checking a diff against them means reading one. It hands back the roots the header declares and the blocks as they were framed, and it checks the one thing a CAR file can be checked for from the inside — that every block hashes to the CID it is filed under. Nothing above it has to trust the sender’s labelling.

What it does not do is walk. A CAR is a bag of blocks in no required order, and which of them matter depends on what the root is — a commit, a tree node, a record — so following links is the caller’s job.

Structs

Car

A CAR file, read apart.

Reader 🔒

A cursor over the length-prefixed sections a CAR file is made of.

Enums

CarError

Why a byte sequence is not a CAR file this crate can read.

Constants

CAR_VERSION 🔒

The CAR container format version this writes. Not a repository version.

Functions

header 🔒

The DAG-CBOR header block: which roots, and which CAR version.

parse_header 🔒

Reads the roots out of a decoded header, and refuses everything else.

read

Reads a CARv1 file.

section_len

How many bytes a block of len bytes filed under cid takes in a CAR file: its length prefix, its CID and the block itself.

split_block 🔒

Splits one block section into the CID it is filed under and its bytes.

write

Writes a CARv1 stream with one root.

write_roots

Writes a CARv1 stream with however many roots it has, including none.

write_section 🔒

Appends one length-prefixed section.

write_varint 🔒

Appends an unsigned LEB128 varint.