{"id":50988209,"url":"https://github.com/lamco-admin/lambutter","last_synced_at":"2026-06-19T22:30:50.940Z","repository":{"id":362162889,"uuid":"1223464342","full_name":"lamco-admin/lambutter","owner":"lamco-admin","description":"no_std read-only btrfs reader for UEFI bootloaders (development repo)","archived":false,"fork":false,"pushed_at":"2026-06-02T23:02:50.000Z","size":287,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T00:22:46.431Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lamco-admin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/SUPPORTED-SCENARIOS.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T10:53:32.000Z","updated_at":"2026-06-02T22:54:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lamco-admin/lambutter","commit_stats":null,"previous_names":["lamco-admin/lambutter"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lamco-admin/lambutter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamco-admin%2Flambutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamco-admin%2Flambutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamco-admin%2Flambutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamco-admin%2Flambutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lamco-admin","download_url":"https://codeload.github.com/lamco-admin/lambutter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lamco-admin%2Flambutter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34550858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-19T22:30:47.938Z","updated_at":"2026-06-19T22:30:50.935Z","avatar_url":"https://github.com/lamco-admin.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lambutter\n\n[![Crates.io](https://img.shields.io/crates/v/lambutter.svg)](https://crates.io/crates/lambutter)\n[![Docs.rs](https://docs.rs/lambutter/badge.svg)](https://docs.rs/lambutter)\n[![CI](https://github.com/lamco-admin/lambutter/actions/workflows/ci.yml/badge.svg)](https://github.com/lamco-admin/lambutter/actions/workflows/ci.yml)\n[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)\n\n**`no_std` read-only btrfs reader for UEFI bootloaders and embedded contexts.**\n\nLambutter is the btrfs counterpart to [`ext4-view`](https://github.com/nicholasbishop/ext4-view-rs):\na pure-Rust, allocation-aware, read-only btrfs filesystem reader designed for\ncontexts that cannot link `std` — UEFI applications, microcontrollers,\nbare-metal kernels, and recovery tooling.\n\n## Status\n\n**v0.3.0 — feature-complete + live-validated** (see\n[`docs/SPEC-LAMBUTTER.md` §2](https://github.com/lamco-admin/lambutter/blob/main/docs/SPEC-LAMBUTTER.md) for scope, and\n[`CHANGELOG.md`](https://github.com/lamco-admin/lambutter/blob/main/CHANGELOG.md) for the version arc through v0.1.0 →\nv0.3.0). Open and read regular files, symlinks, and directory listings\non SINGLE / DUP / RAID1 / RAID1C3 / RAID1C4 btrfs volumes; decode zstd,\nzlib, and LZO extents; surface unsupported profiles (RAID0/10/5/6,\nZONED, RAID_STRIPE_TREE) as typed errors. The public API may add but\nnot break within the v0.3.x line. Data-block CSUM verification and\nsnapshot enumeration are tracked for v0.4.0+.\n\n**Validation posture:**\n- 36 host unit tests, all modules\n- 9 fixture-based oracle tests (uncompressed, zstd, zlib, LZO,\n  DUP-metadata, NO_HOLES sparse, symlinks, read-at chunked, smoke)\n- 5 cargo-fuzz harnesses, 1-hour smoke run completed with zero crashes\n- Live host validation: `examples/inspect.rs` against live openSUSE\n  Tumbleweed btrfs partition with Snapper-managed default-subvol\n  redirect — 6 path reads (regular file 38 MB full-extent walk +\n  inline 11 B + 1.2 KB normal, symlinks in both `/boot` and `/etc`)\n  all sha256-byte-identical to kernel oracle\n- **Live embedded validation**: linked into [LamBoot](https://lamboot.dev)\n  (Lamco's UEFI bootloader) as the native btrfs backend, booting\n  openSUSE Tumbleweed end-to-end under live UEFI firmware with full\n  trust-chain attribution.\n\n## Use\n\n```rust\nuse lambutter::{Btrfs, Path};\n\nlet mut fs = Btrfs::open(reader, device_size_bytes)?;\n\n// Resolve and read a file in one shot (loads the whole file into memory).\nlet kernel = fs.read_file(Path::new(b\"/vmlinuz\")?)?;\n\n// Or stream it in fixed-size chunks (bounded memory).\nlet inode = fs.resolve(Path::new(b\"/vmlinuz\")?)?;\nlet mut buf = [0u8; 64 * 1024];\nlet mut off = 0u64;\nloop {\n    let n = fs.read_file_at(\u0026inode, off, \u0026mut buf)?;\n    if n == 0 { break; }\n    process(\u0026buf[..n]);\n    off += n as u64;\n}\n```\n\nFor integrating from another `no_std` Rust project — including the\n`BlockRead` impl patterns for UEFI `EFI_BLOCK_IO_PROTOCOL`, file-backed\nhost testing, and the standard symlink-follow pattern — see the\n[Consumer Guide](https://github.com/lamco-admin/lambutter/blob/main/docs/CONSUMER-GUIDE.md).\n\nA worked end-to-end example lives at `examples/inspect.rs`: a host-side\nCLI that opens any block device or image file, reports the resolved\ndefault-subvol objectid, and reads a named file printing size + sha256\n+ first 16 bytes. Built with `cargo build --release --example inspect`;\nrun as root against a real device for live validation.\n\n## Goals\n\n- Read-only by design. The crate cannot mutate a btrfs volume.\n- `no_std` + `alloc`. No `std`, no `tokio`, no async machinery.\n- Sufficient subset for `/boot` reading on stock Linux distributions\n  (openSUSE Tumbleweed/Leap, Fedora Workstation, CachyOS, Garuda) under\n  Secure Boot.\n- Fuzz-tested against malformed inputs.\n- Independent of any other btrfs crate. Implemented from the on-disk format\n  specification, not derived from existing parsers.\n\n## Non-goals\n\n- Write support of any kind.\n- `bcachefs` / `zfs` / `xfs`. Each is its own filesystem; this crate is\n  btrfs-only.\n- Replacing the kernel's btrfs driver. Lambutter is for code paths where\n  the kernel is not yet running.\n\n## Features (Cargo)\n\n| Feature | Default | What it enables |\n|---|---|---|\n| `zstd` | yes | zstd-compressed extent decoding via `ruzstd` (Tumbleweed / Fedora F34+ default) |\n| `zlib` | no | zlib-compressed extent decoding via `miniz_oxide` (legacy default) |\n| `lzo` | no | LZO-compressed extent decoding via `lzokay` (rare in modern installs) |\n| `std` | no | enables `std::error::Error` impl on `Error` (host-only) |\n\nFor UEFI bootloaders that may encounter any compression on `/boot`,\nenable all three: `features = [\"zstd\", \"zlib\", \"lzo\"]`.\n\n## Documentation\n\n- [`docs/SPEC-LAMBUTTER.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/SPEC-LAMBUTTER.md) — design spec, on-disk format scope\n- [`docs/FEATURES.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/FEATURES.md) — exhaustive feature inventory + non-features\n- [`docs/SUPPORTED-SCENARIOS.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/SUPPORTED-SCENARIOS.md) — distro × btrfs-config coverage matrix\n- [`docs/CONSUMER-GUIDE.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/CONSUMER-GUIDE.md) — integrating lambutter into a downstream `no_std` Rust project\n- [`docs/TROUBLESHOOTING.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/TROUBLESHOOTING.md) — error catalogue (symptom → cause → fix)\n- [`docs/TESTING-AND-FUZZING-PLAN.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/TESTING-AND-FUZZING-PLAN.md) — test/fuzz strategy + validation results\n- [`docs/PRE-PUBLISH-AND-TESTING-PLAN.md`](https://github.com/lamco-admin/lambutter/blob/main/docs/PRE-PUBLISH-AND-TESTING-PLAN.md) — pre-publish hygiene checklist\n- [`CHANGELOG.md`](https://github.com/lamco-admin/lambutter/blob/main/CHANGELOG.md) — version history\n\n## License\n\nDual-licensed under MIT or Apache-2.0, at your option. See\n[`LICENSE-MIT`](https://github.com/lamco-admin/lambutter/blob/main/LICENSE-MIT) and [`LICENSE-APACHE`](https://github.com/lamco-admin/lambutter/blob/main/LICENSE-APACHE).\n\n## Contributing\n\nContributions welcome — particularly:\n\n- Additional fixture scenarios (`tests/fixtures/`)\n- Per-distro real-world validation across the wider ecosystem\n- v0.2.x scope items: data-block CSUM_TREE verification, snapshot\n  enumeration, full subvolume traversal\n\nSee `docs/SPEC-LAMBUTTER.md` for design constraints before opening a PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flamco-admin%2Flambutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flamco-admin%2Flambutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flamco-admin%2Flambutter/lists"}