neco-car 0.1.1

necosystems series CAR v1 parser and writer for content-addressable archives
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# neco-car

[日本語](README-ja.md)

A CAR v1 (Content Addressable aRchive) parser and writer for the IPFS/IPLD ecosystem. Depends on [neco-cbor](../neco-cbor) for DAG-CBOR header decoding and [neco-cid](../neco-cid) for CID parsing.

## Features

- Parse CAR v1 files: varint-prefixed DAG-CBOR header + varint-prefixed CID+data blocks
- Write CAR v1 files from a list of roots and raw blocks
- Comprehensive `CarError` enum covering all parse and write failure cases
- No unsafe code

## Usage

### Parse a CAR v1 file

```rust
use neco_car::{parse_v1, CarV1};

let bytes: &[u8] = /* raw CAR bytes */ &[];
let car = parse_v1(bytes).unwrap();

for root in car.roots() {
    println!("root: {root}");
}

for block in car.blocks() {
    println!("cid={}, len={}", block.cid(), block.data().len());
}
```

### Decompose into owned parts

```rust
let (roots, blocks) = car.into_parts();
for (cid, data) in blocks.into_iter().map(|e| e.into_parts()) {
    // cid: Cid, data: Vec<u8>
}
```

### Write a CAR v1 file

```rust
use neco_car::write_v1;
use neco_cid::Cid;

let root: Cid = /* your root CID */ todo!();
let block_data: &[u8] = b"...";

let car_bytes = write_v1(&[root.clone()], &[(root, block_data)]).unwrap();
```

## API

### Top-level functions

| Item | Description |
|------|-------------|
| `parse_v1(input: &[u8]) -> Result<CarV1, CarError>` | Parse a byte slice as a CAR v1 archive |
| `write_v1(roots: &[Cid], blocks: &[(Cid, &[u8])]) -> Result<Vec<u8>, CarError>` | Encode roots and blocks as a CAR v1 archive |

### `CarV1`

Represents a parsed CAR v1 archive.

| Method | Description |
|--------|-------------|
| `roots() -> &[Cid]` | Slice of root CIDs declared in the header |
| `blocks() -> &[CarEntry]` | Slice of all blocks in the archive |
| `into_parts() -> (Vec<Cid>, Vec<CarEntry>)` | Consume and decompose into owned roots and blocks |

### `CarEntry`

A single block within a CAR archive.

| Method | Description |
|--------|-------------|
| `cid() -> &Cid` | The CID identifying this block |
| `data() -> &[u8]` | The raw block data |
| `into_parts() -> (Cid, Vec<u8>)` | Consume and decompose into owned CID and data |

### `CarError`

| Variant | Description |
|---------|-------------|
| `UnexpectedEnd` | Input ended prematurely |
| `VarintOverflow` | Varint value exceeds 64-bit range |
| `InvalidHeader(DecodeErrorKind)` | DAG-CBOR header failed to decode |
| `HeaderNotMap` | Header is not a CBOR map |
| `MissingHeaderField(&'static str)` | Required header field (`version` or `roots`) is absent |
| `UnsupportedVersion(u64)` | CAR version is not 1 |
| `RootsNotArray` | `roots` field is not a CBOR array |
| `InvalidRootCid(CidError)` | A root CID could not be parsed |
| `InvalidBlockCid(CidError)` | A block CID could not be parsed |
| `BlockLengthMismatch` | Block section length is inconsistent with CID size |
| `EmptySection` | A block section has zero length |
| `InvalidCidLink` | Root CID link is not a valid tag-42 DAG-CBOR link |
| `HeaderEncode(EncodeError)` | DAG-CBOR header encoding failed during write |

## License

MIT