apple / apple/containerization

[Request]: Implement deep extent tree support (depth >= 2) in ContainerizationEXT4

Open
#645 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
8.9k
Forks
359
Avg merge
2d 20h
Merged PRs (30d)
13

Description

### Feature or enhancement request details

## Summary

The EXT4 reader and formatter currently only support extent trees of depth 0 and 1. When encountering depth >= 2, the reader throws `deepExtentsUnimplemented` and the formatter throws `fileTooBig`.

## Where in the code

- **Reader**: `EXT4+Reader.swift` line 246 — `getExtents()` has a `default` case that throws `Error.deepExtentsUnimplemented`
- **Formatter**: `EXT4+Formatter.swift` line 1168 — `writeExtents()` has a `default` case that throws `Error.fileTooBig`
- **Related bug**: `EXT4+Formatter.swift` line 1148 — force-unwrap `leafNode.leaves.last!.block` can crash if the leaves array is empty at a depth-1 boundary edge case

## When this matters

- Reading a pre-existing ext4 image (not created by this formatter) that contains files with highly fragmented extent trees (depth >= 2)
- Writing a file with more than ~1,360 non-contiguous extents (exceeds depth-1 capacity of 4 x 340 leaves)
- Overlay layer whiteouts that cause block fragmentation across multiple unpack passes

These are uncommon in typical container workflows (freshly written images are mostly contiguous), but the current behavior is a hard crash/error with no workaround.

## Proposed changes

1. **Reader**: Convert the depth-1 special case in `getExtents()` to a recursive/iterative descent that handles any depth — follow ExtentIndex nodes until reaching depth-0 ExtentLeaf nodes
2. **Formatter**: Extend `writeExtents()` to build multi-level extent trees when the number of extents exceeds depth-1 capacity
3. **Bug fix**: Replace the force-unwrap at line 1148 with safe optional access
4. **Tests**: Add test cases for reading and writing extent trees at depth 0, 1, and 2+

I'd like to work on this. Planning to split into two PRs:
- PR 1: Reader support for depth >= 2 + tests
- PR 2: Formatter support for depth >= 2 + force-unwrap fix + tests

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.