use std::collections::{BTreeMap, HashMap, HashSet};
use std::io::{Read, Seek, SeekFrom, Write};
use crate::acl::Acl;
use crate::csum::{Checksummer, Crc32c};
use crate::extent::{ExtentNode, MAX_EXTENT_DEPTH, parse_node, tail_offset};
use crate::feature::{FeatureSet, Incompat, LARGE_FILE_MIN_SIZE, Profile, RoCompat};
use crate::fidelity::Synthesis;
use crate::finding::{Family, Finding, Findings, Severity};
use crate::geometry::carries_superblock;
use crate::io::{Bounded, offset_of, read_exact_at};
use crate::model::ROOT_INO;
#[cfg(test)]
use crate::ondisk::parse_inline;
use crate::ondisk::{
BG_BLOCK_UNINIT, BG_INODE_UNINIT, DIR_TAIL_LEN, DX_CHECKSUM_OFFSET, DX_ENTRY_LEN,
DX_HASH_CONTINUED, DX_MAX_INDIRECT_LEVELS, DX_NODE_COUNT_OFFSET, DX_ROOT_COUNT_OFFSET,
DX_TAIL_LEN, DirEntry, DxEntry, EXTENT_ENTRY_SIZE, EXTENT_TAIL_LEN, FileType,
GOOD_OLD_FIRST_INODE, GOOD_OLD_INODE_SIZE, GroupDescriptor, Inode, InodeFlags, MMP_MAGIC,
MMP_SEQ_CLEAN, MMP_SEQ_FSCK, MMP_SEQ_MAX, Mmp, ParseError, STATE_CLEAN, STATE_ERRORS,
SuperBlock, XATTR_CHECKSUM_OFFSET, decode_device, dx_tail_offset, get_u16, get_u32,
orphan_entries_len, parse_block_stored, parse_inline_stored, put_u16, read_dx_entries,
read_dx_root_info, read_orphan_tail, superblock_checksum,
};
use crate::ondisk::{StoredXattr, XattrValue};
use crate::path::is_hostile_entry;
use crate::csum as recipe;
use crate::policy::{Limits, ReadPolicy};
use crate::source::Metadata;
use crate::tree::{Attributes, Bound, Child, FsTree, NodeKind, TreeEntry, TreeError, Usage};
use crate::xattr::Xattr;
const SUPPORTED_INCOMPAT: u32 = Incompat::FILETYPE.bits()
| Incompat::EXTENTS.bits()
| Incompat::SIXTY_FOUR_BIT.bits()
| Incompat::FLEX_BG.bits()
| Incompat::CSUM_SEED.bits()
| Incompat::META_BG.bits()
| INCOMPAT_RECOVER
| INCOMPAT_ENCRYPT
| INCOMPAT_EA_INODE
| INCOMPAT_LARGEDIR
| INCOMPAT_INLINE_DATA
| INCOMPAT_CASEFOLD
| INCOMPAT_MMP;
pub(crate) const INCOMPAT_MMP: u32 = 0x0000_0100;
pub(crate) const INCOMPAT_RECOVER: u32 = 0x0000_0004;
pub(crate) const INCOMPAT_ENCRYPT: u32 = 0x0001_0000;
pub(crate) const INCOMPAT_EA_INODE: u32 = 0x0000_0400;
const MAX_XATTR_VALUE: u32 = 65_536;
pub(crate) const RO_COMPAT_GDT_CSUM: u32 = 0x0000_0010;
pub(crate) const RO_COMPAT_BIGALLOC: u32 = 0x0000_0200;
pub(crate) const INCOMPAT_LARGEDIR: u32 = 0x0000_4000;
pub(crate) const INCOMPAT_INLINE_DATA: u32 = 0x0000_8000;
pub(crate) const INCOMPAT_CASEFOLD: u32 = 0x0002_0000;
fn unsupported_incompat(incompat: Incompat) -> u32 {
incompat.bits() & !SUPPORTED_INCOMPAT
}
const UNMODELLED_INCOMPAT: &[(&str, u32)] = &[
("compression", 0x0000_0001),
("needs_recovery", 0x0000_0004),
("journal_dev", 0x0000_0008),
("mmp", 0x0000_0100),
("ea_inode", 0x0000_0400),
("dirdata", 0x0000_1000),
("large_dir", 0x0000_4000),
("inline_data", 0x0000_8000),
("encrypt", 0x0001_0000),
("casefold", 0x0002_0000),
];
#[must_use]
pub fn incompat_name(bit: u32) -> Option<&'static str> {
if bit.count_ones() != 1 {
return None;
}
Incompat::from_bits(bit)
.names()
.first()
.copied()
.or_else(|| {
UNMODELLED_INCOMPAT
.iter()
.find(|(_, b)| *b == bit)
.map(|(name, _)| *name)
})
}
const UNMODELLED_RO_COMPAT: &[(&str, u32)] = &[
("uninit_bg", 0x0000_0010),
("quota", 0x0000_0100),
("bigalloc", 0x0000_0200),
("replica", 0x0000_0800),
("read-only", 0x0000_1000),
("project", 0x0000_2000),
("shared_blocks", 0x0000_4000),
("verity", 0x0000_8000),
("orphan_present", 0x0001_0000),
];
#[must_use]
pub fn ro_compat_name(bit: u32) -> Option<&'static str> {
if bit.count_ones() != 1 {
return None;
}
RoCompat::from_bits(bit)
.names()
.first()
.copied()
.or_else(|| {
UNMODELLED_RO_COMPAT
.iter()
.find(|(_, b)| *b == bit)
.map(|(name, _)| *name)
})
}
fn describe_unsupported_incompat(bits: u32) -> String {
let mut parts: Vec<String> = Vec::new();
let mut undefined = 0u32;
for i in 0..u32::BITS {
let bit = 1u32 << i;
if bits & bit == 0 {
continue;
}
if let Some(name) = incompat_name(bit) {
parts.push(name.to_string());
} else {
undefined |= bit;
}
}
if undefined != 0 {
parts.push(format!("{undefined:#010x}"));
}
format!(
"unsupported incompatible feature(s) {}: the reader cannot be certain it \
interprets the on-disk format correctly",
parts.join(", ")
)
}
const DIRECT_BLOCKS: usize = 12;
const INDIRECT_LEVELS: u32 = 3;
const MAP_WINDOW_BLOCKS: usize = 4096;
const MAX_RUN_BYTES: usize = 256 * 1024;
const TABLE_CACHE_BYTES: usize = 256 * 1024;
type TableCache = crate::cache::BlockCache<Vec<u8>>;
fn table_cache(block_size: usize) -> TableCache {
TableCache::within(TABLE_CACHE_BYTES, block_size, 4)
}
struct DirIndex {
blocks: Vec<u64>,
root: Vec<u8>,
levels: u8,
version: crate::hash::HashVersion,
signedness: crate::hash::HashSignedness,
}
type IndexPath = Vec<(Vec<DxEntry>, usize)>;
type JudgedLeaf = (
u64,
u32,
Option<u32>,
crate::hash::HashVersion,
crate::hash::HashSignedness,
Names,
);
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
enum Indexed {
Found(u32),
Absent,
Unusable,
}
enum Step {
Leaf(u32),
End,
Unusable,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct Run {
at: usize,
phys: u64,
len: usize,
}
fn runs(map: &[u64], max: usize) -> Vec<Run> {
let max = max.max(1);
let mut out: Vec<Run> = Vec::new();
for (at, &phys) in map.iter().enumerate() {
if let Some(run) = out.last_mut() {
let continues = if run.phys == 0 {
phys == 0
} else {
phys != 0 && run.phys.checked_add(run.len as u64) == Some(phys)
};
if continues && run.len < max {
run.len += 1;
continue;
}
}
out.push(Run { at, phys, len: 1 });
}
out
}
const MAX_LOGICAL_BLOCKS: u64 = 1 << 32;
use crate::policy::MAX_PATH;
pub const MIN_DIRENT_LEN: u64 = 12;
fn is_dir(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o040000
}
fn is_symlink(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o120000
}
fn is_regular(inode: &Inode) -> bool {
inode.mode & 0o170000 == 0o100000
}
fn is_inline(inode: &Inode) -> bool {
inode.flags.contains(InodeFlags::INLINE_DATA)
}
fn inline_extension(inode: &Inode) -> Result<Vec<u8>, ReadError> {
let found = parse_inline_stored(&inode.inline_xattr)?
.into_iter()
.find(|entry| entry.index == 7 && entry.name == b"system.data");
match found {
Some(StoredXattr {
value: XattrValue::Here(value),
..
}) => Ok(value),
Some(_) => Err(ReadError::BadInlineData {
fault: "its system.data names an inode of its own",
}),
None => Err(ReadError::BadInlineData {
fault: "it has no system.data attribute",
}),
}
}
fn inline_dir_regions(inode: &Inode) -> Result<[Vec<u8>; 2], ReadError> {
Ok([inode.block[4..].to_vec(), inline_extension(inode)?])
}
fn refuse_ciphertext(inode: &Inode) -> Result<(), ReadError> {
if !inode.flags.contains(InodeFlags::ENCRYPT) {
return Ok(());
}
let node = if is_dir(inode) {
"directory"
} else if is_symlink(inode) {
"symbolic link"
} else {
"file"
};
Err(ReadError::Encrypted { node })
}
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
enum Names {
Plain,
Ciphertext,
}
impl Names {
fn of(dir: &Inode) -> Self {
if dir.flags.contains(InodeFlags::ENCRYPT) {
Names::Ciphertext
} else {
Names::Plain
}
}
}
const TARGET_IN_BLOCK_AREA_BELOW: u64 = 60;
fn target_in_block_area(inode: &Inode) -> bool {
inode.size < TARGET_IN_BLOCK_AREA_BELOW && !inode.flags.contains(InodeFlags::EXTENTS)
}
fn maps_data(inode: &Inode) -> bool {
if is_inline(inode) {
return false;
}
match inode.mode & 0o170000 {
0o100000 | 0o040000 => true, 0o120000 => !target_in_block_area(inode), _ => false,
}
}
#[derive(Clone, Copy, Debug)]
enum RecordFault {
Framing,
Name,
Reference,
}
fn mmp_state(sequence: u32) -> &'static str {
match sequence {
MMP_SEQ_FSCK => "a checker was running",
0..=MMP_SEQ_MAX => "a host had the filesystem open",
_ => "a value the format gives no meaning",
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum Category {
Superblock,
GroupDescriptor,
Bitmap,
Inode,
ExtentTree,
Directory,
Xattr,
Journal,
Orphan,
Source,
}
impl Category {
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Category::Superblock => "superblock",
Category::GroupDescriptor => "group descriptor",
Category::Bitmap => "bitmap",
Category::Inode => "inode",
Category::ExtentTree => "extent tree",
Category::Directory => "directory",
Category::Xattr => "xattr",
Category::Journal => "journal",
Category::Orphan => "orphan",
Category::Source => "source",
}
}
}
crate::naming::serialize_as_name!(Category);
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Location {
pub block: Option<u64>,
pub group: Option<u32>,
pub inode: Option<u32>,
}
impl Location {
#[must_use]
pub const fn or(self, other: Self) -> Self {
Self {
block: match self.block {
Some(b) => Some(b),
None => other.block,
},
group: match self.group {
Some(g) => Some(g),
None => other.group,
},
inode: match self.inode {
Some(i) => Some(i),
None => other.inode,
},
}
}
#[must_use]
pub const fn at_inode(inode: u32) -> Self {
Self {
block: None,
group: None,
inode: Some(inode),
}
}
#[must_use]
pub const fn at_group(group: u32) -> Self {
Self {
block: None,
group: Some(group),
inode: None,
}
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Anomaly {
pub severity: Severity,
pub category: Category,
pub location: Location,
pub detail: String,
}
impl crate::Deviation for Anomaly {
fn severity(&self) -> Severity {
self.severity
}
fn is_source_failure(&self) -> bool {
self.category == Category::Source
}
fn to_finding(&self, unit: u32) -> Finding {
Anomaly::to_finding(self, unit)
}
}
impl Anomaly {
#[must_use]
pub fn to_finding(&self, block_size: u32) -> Finding {
let Self {
severity,
category,
location,
detail,
} = self;
let Location {
block,
group,
inode,
} = *location;
crate::finding::project(
*severity,
Family::Ext,
category.as_str(),
&[
("group", group.map(u64::from)),
("inode", inode.map(u64::from)),
("block", block),
],
block,
block_size,
detail,
)
}
}
fn check_checksum(
object: &'static str,
index: u64,
stored: u32,
computed: u32,
) -> Result<(), ReadError> {
if stored == computed {
return Ok(());
}
Err(ReadError::ChecksumMismatch {
object,
index,
stored,
computed,
})
}
fn anomaly_at_inode(err: &ReadError, ino: u32) -> Anomaly {
let mut a = err.anomaly();
a.location = a.location.or(Location::at_inode(ino));
a
}
fn redirect_block_ref(a: &mut Anomaly, err: &ReadError, category: Category) {
if matches!(err, ReadError::OutOfRange { what: "block", .. }) {
a.category = category;
}
}
fn anomaly_in_mapping(err: &ReadError, ino: u32, category: Category) -> Anomaly {
let mut a = err.anomaly();
redirect_block_ref(&mut a, err, category);
if ino != 0 {
a.location = a.location.or(Location::at_inode(ino));
}
a
}
fn anomaly_in_bitmap(err: &ReadError, group: u32, category: Category) -> Anomaly {
let mut a = err.anomaly();
redirect_block_ref(&mut a, err, category);
a.location = a.location.or(Location::at_group(group));
a
}
fn parse_structure(err: &ParseError) -> &'static str {
match err {
ParseError::TooShort { structure, .. }
| ParseError::BadMagic { structure, .. }
| ParseError::InvalidField { structure, .. } => structure,
}
}
fn parse_category(structure: &str) -> Category {
match structure {
"Inode" => Category::Inode,
"GroupDescriptor" => Category::GroupDescriptor,
"ExtentHeader" | "ExtentNode" => Category::ExtentTree,
"DirEntry" | "DirEntryTail" => Category::Directory,
s if s.starts_with("Dx") => Category::Directory,
s if s.starts_with("Xattr") => Category::Xattr,
s if s.starts_with("JournalSuperblock") => Category::Journal,
"OrphanBlockTail" => Category::Orphan,
_ => Category::Superblock,
}
}
struct ExtentScanCtx<'a> {
ino: u32,
seed: u32,
has_csum: bool,
csum: &'a Crc32c,
}
fn extent_tail_offset(node: &[u8], node_bytes: usize) -> usize {
if node.len() >= EXTENT_ENTRY_SIZE {
let eh_max = usize::from(get_u16(node, 4));
let tail = EXTENT_ENTRY_SIZE * (eh_max + 1);
if tail + EXTENT_TAIL_LEN <= node.len() {
return tail;
}
}
tail_offset(node_bytes)
}
#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum ReadError {
#[error("i/o error: {message}")]
#[non_exhaustive]
Io {
kind: std::io::ErrorKind,
message: String,
},
#[error(transparent)]
Parse(#[from] ParseError),
#[error("reference to {what} {index} is out of range")]
#[non_exhaustive]
OutOfRange {
what: &'static str,
index: u64,
},
#[error("the filesystem records {blocks} blocks and its source holds {held}")]
#[non_exhaustive]
SourceTooShort {
blocks: u64,
held: u64,
},
#[error("inode {inode} does not exist")]
#[non_exhaustive]
NoSuchInode {
inode: u32,
},
#[error("extent tree is too deep or malformed")]
BadExtentTree,
#[error("directory structure is malformed")]
BadDirectory,
#[error("a directory entry names inode {inode}, which the filesystem does not have")]
#[non_exhaustive]
DirEntryNoSuchInode {
inode: u32,
},
#[error("a directory entry naming inode {inode} has a name no directory can hold")]
#[non_exhaustive]
HostileName {
inode: u32,
},
#[error(
"a directory entry naming inode {inode} sits in a leaf its hash does not lead to, so \
a lookup through the index misses it"
)]
#[non_exhaustive]
IndexMisplacesName {
inode: u32,
},
#[error(
"a directory entry names directory inode {inode}, which the tree reaches by another \
name as well"
)]
#[non_exhaustive]
RepeatedDirectory {
inode: u32,
},
#[error(
"the directories up to inode {inode} claim more blocks than the filesystem holds, so \
directories share their blocks"
)]
#[non_exhaustive]
DirectoryBlocksShared {
inode: u32,
},
#[error("inode {inode} is in use, in a group its descriptor marks as holding no inode in use")]
#[non_exhaustive]
InodeInUninitGroup {
inode: u32,
},
#[error(
"group {group}'s descriptor marks it uninitialized (flags {flags:#06x}) on a filesystem \
without a feature defining the flag"
)]
#[non_exhaustive]
UninitFlagWithoutFeature {
group: u32,
flags: u16,
},
#[error("the filesystem uses {layout}, which this reader does not read")]
#[non_exhaustive]
UnsupportedLayout {
layout: &'static str,
},
#[error("journal structure is malformed")]
BadJournal,
#[error("the journal needs recovery and uses {feature}, which this reader does not replay")]
#[non_exhaustive]
JournalUnsupported {
feature: &'static str,
},
#[error("the journal's log is malformed at log block {log_block}: {detail}")]
#[non_exhaustive]
JournalMalformed {
log_block: u32,
detail: &'static str,
},
#[error(
"the journal's copy of block {block} in transaction {sequence} fails its checksum: \
stored {stored:#010x}, computed {computed:#010x}"
)]
#[non_exhaustive]
JournalCopyChecksum {
block: u64,
sequence: u32,
stored: u32,
computed: u32,
},
#[error("orphan file structure is malformed")]
BadOrphanFile,
#[error("{}", crate::finding::NOT_CLEANLY_UNMOUNTED)]
NotCleanlyUnmounted,
#[error("a driver recorded that it found errors in this filesystem")]
ErrorsDetected,
#[error(
"block {block}, which the superblock names for multiple-mount protection, holds no record of it"
)]
#[non_exhaustive]
BadMmpBlock {
block: u64,
},
#[error("the multiple-mount protection block records sequence {sequence:#010x}: {}", mmp_state(*.sequence))]
#[non_exhaustive]
MmpInUse {
sequence: u32,
},
#[error(
"unsupported incompatible feature bits {bits:#010x}: the reader cannot be certain \
it interprets the on-disk format correctly"
)]
#[non_exhaustive]
UnsupportedIncompat {
bits: u32,
},
#[error("an inline inode's content: {fault}")]
#[non_exhaustive]
BadInlineData {
fault: &'static str,
},
#[error("the inode {inode} an attribute keeps its value in: {fault}")]
#[non_exhaustive]
BadValueInode {
inode: u32,
fault: &'static str,
},
#[error("the {node} is encrypted, and what it holds is ciphertext this reader has no key to")]
#[non_exhaustive]
Encrypted {
node: &'static str,
},
#[error(
"inode {inode} is in extent format, but the superblock does not enable the \
extent feature"
)]
#[non_exhaustive]
ExtentFlagWithoutFeature {
inode: u32,
},
#[error(
"inode {inode} names attribute block {block}, but the superblock does not enable \
the ext_attr feature"
)]
#[non_exhaustive]
XattrBlockWithoutFeature {
inode: u32,
block: u64,
},
#[error(
"the {} attribute is not an ACL: {source}",
crate::escape::printable(.name)
)]
#[non_exhaustive]
MalformedAcl {
name: Vec<u8>,
#[source]
source: crate::acl::AclError,
},
#[error(
"inode {inode} is a {size}-byte regular file, but the superblock does not enable \
the large_file feature"
)]
#[non_exhaustive]
LargeFileWithoutFeature {
inode: u32,
size: u64,
},
#[error(
"inode {inode} is marked hash-indexed, but the superblock does not enable the \
dir_index feature"
)]
#[non_exhaustive]
IndexFlagWithoutFeature {
inode: u32,
},
#[error("inode {inode} is marked hash-indexed, but it is not a directory")]
#[non_exhaustive]
IndexFlagOnNonDirectory {
inode: u32,
},
#[error("{what} for group {group} lies at block {block}, outside the group")]
#[non_exhaustive]
MetadataOutsideGroup {
what: &'static str,
group: u32,
block: u64,
},
#[error("no such path: {}", crate::escape::printable(path))]
#[non_exhaustive]
NotFound {
path: Vec<u8>,
},
#[error("not a directory: {}", crate::escape::printable(path))]
#[non_exhaustive]
NotADirectory {
path: Vec<u8>,
},
#[error(
"too many symbolic links resolving: {}",
crate::escape::printable(path)
)]
#[non_exhaustive]
SymlinkLoop {
path: Vec<u8>,
},
#[error("a walked path is longer than the {limit} bytes a walk builds")]
#[non_exhaustive]
PathTooLong {
limit: usize,
},
#[error("the tree holds more than {limit} names, the bound this walk is held to")]
#[non_exhaustive]
WalkTooLarge {
limit: usize,
},
#[error("the file is {size} bytes, more than the {limit}-byte cap this read is held to")]
#[non_exhaustive]
FileTooLarge {
size: u64,
limit: u64,
},
#[error("{object} {index} checksum mismatch: stored {stored:#010x}, computed {computed:#010x}")]
#[non_exhaustive]
ChecksumMismatch {
object: &'static str,
index: u64,
stored: u32,
computed: u32,
},
}
crate::io::io_error!(ReadError);
impl ReadError {
#[must_use]
pub fn anomaly(&self) -> Anomaly {
let (severity, category, location) = match self {
ReadError::Io {
kind: std::io::ErrorKind::UnexpectedEof,
..
} => (
Severity::Structural,
Category::Superblock,
Location::default(),
),
ReadError::Io { .. } => (Severity::Structural, Category::Source, Location::default()),
ReadError::Parse(e) => (
Severity::Structural,
parse_category(parse_structure(e)),
Location::default(),
),
ReadError::OutOfRange { what, index } => {
let category = if *what == "inode" {
Category::Inode
} else if *what == "group" {
Category::GroupDescriptor
} else {
Category::Superblock
};
let location = match *what {
"block" => Location {
block: Some(*index),
..Location::default()
},
"inode" => Location {
inode: Some(*index as u32),
..Location::default()
},
"group" => Location {
group: Some(*index as u32),
..Location::default()
},
_ => Location::default(),
};
(Severity::Structural, category, location)
}
ReadError::SourceTooShort { .. } => (
Severity::Structural,
Category::Superblock,
Location::default(),
),
ReadError::NoSuchInode { inode: n } => (
Severity::Structural,
Category::Inode,
Location {
inode: Some(*n),
..Location::default()
},
),
ReadError::BadExtentTree => (
Severity::Structural,
Category::ExtentTree,
Location::default(),
),
ReadError::BadDirectory => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::DirEntryNoSuchInode { .. }
| ReadError::InodeInUninitGroup { .. }
| ReadError::HostileName { .. }
| ReadError::IndexMisplacesName { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::DirectoryBlocksShared { inode } => (
Severity::Structural,
Category::Directory,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::RepeatedDirectory { inode } => (
Severity::Integrity,
Category::Directory,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::BadJournal
| ReadError::JournalUnsupported { .. }
| ReadError::JournalMalformed { .. } => {
(Severity::Structural, Category::Journal, Location::default())
}
ReadError::JournalCopyChecksum { block, .. } => (
Severity::Integrity,
Category::Journal,
Location {
block: Some(*block),
..Location::default()
},
),
ReadError::BadOrphanFile => {
(Severity::Structural, Category::Orphan, Location::default())
}
ReadError::BadMmpBlock { block } => (
Severity::Structural,
Category::Superblock,
Location {
block: Some(*block),
..Location::default()
},
),
ReadError::PathTooLong { .. } | ReadError::WalkTooLarge { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::FileTooLarge { .. } => {
(Severity::Structural, Category::Inode, Location::default())
}
ReadError::Encrypted { .. } => {
(Severity::Structural, Category::Inode, Location::default())
}
ReadError::NotFound { .. }
| ReadError::NotADirectory { .. }
| ReadError::SymlinkLoop { .. } => (
Severity::Structural,
Category::Directory,
Location::default(),
),
ReadError::ChecksumMismatch { object, index, .. } => {
let (category, location) = match *object {
"superblock" => (Category::Superblock, Location::default()),
"group descriptor" => (
Category::GroupDescriptor,
Location {
group: Some(*index as u32),
..Location::default()
},
),
"inode" => (
Category::Inode,
Location {
inode: Some(*index as u32),
..Location::default()
},
),
"extent node" => (
Category::ExtentTree,
Location {
block: Some(*index),
..Location::default()
},
),
"block bitmap" | "inode bitmap" => (
Category::Bitmap,
Location {
group: Some(*index as u32),
..Location::default()
},
),
"directory block" => (
Category::Directory,
Location {
block: Some(*index),
..Location::default()
},
),
"xattr block" => (
Category::Xattr,
Location {
block: Some(*index),
..Location::default()
},
),
"journal superblock" | "journal descriptor" | "journal revoke block" => {
(Category::Journal, Location::default())
}
"orphan block" => (
Category::Orphan,
Location {
block: Some(*index),
..Location::default()
},
),
_ => (Category::Superblock, Location::default()),
};
(Severity::Integrity, category, location)
}
ReadError::NotCleanlyUnmounted
| ReadError::ErrorsDetected
| ReadError::MmpInUse { .. } => (
Severity::Cosmetic,
Category::Superblock,
Location::default(),
),
ReadError::UnsupportedIncompat { .. } | ReadError::UnsupportedLayout { .. } => (
Severity::Structural,
Category::Superblock,
Location::default(),
),
ReadError::ExtentFlagWithoutFeature { inode } => (
Severity::Structural,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::XattrBlockWithoutFeature { inode, block } => (
Severity::Structural,
Category::Xattr,
Location {
inode: Some(*inode),
block: Some(*block),
..Location::default()
},
),
ReadError::MalformedAcl { .. } => {
(Severity::Structural, Category::Xattr, Location::default())
}
ReadError::BadInlineData { .. } => {
(Severity::Structural, Category::Inode, Location::default())
}
ReadError::BadValueInode { inode, .. } => (
Severity::Structural,
Category::Xattr,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::LargeFileWithoutFeature { inode, .. } => (
Severity::Conformance,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::UninitFlagWithoutFeature { group, .. } => (
Severity::Conformance,
Category::GroupDescriptor,
Location {
group: Some(*group),
..Location::default()
},
),
ReadError::IndexFlagWithoutFeature { inode } => (
Severity::Conformance,
Category::Directory,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::IndexFlagOnNonDirectory { inode } => (
Severity::Conformance,
Category::Inode,
Location {
inode: Some(*inode),
..Location::default()
},
),
ReadError::MetadataOutsideGroup {
what, group, block, ..
} => {
let category = if what.ends_with("bitmap") {
Category::Bitmap
} else {
Category::GroupDescriptor
};
(
Severity::Structural,
category,
Location {
group: Some(*group),
block: Some(*block),
..Location::default()
},
)
}
};
let detail = match self {
ReadError::UnsupportedIncompat { bits } => describe_unsupported_incompat(*bits),
_ => self.to_string(),
};
Anomaly {
severity,
category,
location,
detail,
}
}
}
pub type ScanReport = crate::ScanReport<Anomaly>;
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Entry {
pub name: Vec<u8>,
pub inode: u32,
pub file_type: FileType,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct WalkEntry {
pub path: Vec<u8>,
pub number: u32,
pub inode: Inode,
}
pub struct Reader<R> {
src: Bounded<R>,
base: u64,
source_len: u64,
sb: SuperBlock,
sb_raw: Vec<u8>,
feature: FeatureSet,
block_size: usize,
policy: ReadPolicy,
limits: Limits,
csum_seed: Option<u32>,
table_cache: TableCache,
needs_recovery: bool,
state_on_disk: u16,
journal: Option<Box<Recovery>>,
}
struct Recovery {
overlay: BTreeMap<u64, crate::replay::Copy>,
outcome: Outcome,
}
enum Outcome {
Replayed(JournalReplay, Vec<ReadError>),
NotReplayed(ReadError),
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct JournalReplay {
pub transactions: u32,
pub blocks: u64,
pub skipped: u32,
}
#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
pub struct OpenOptions {
pub common: crate::OpenOptions,
pub csum_seed: Option<u32>,
}
impl OpenOptions {
#[must_use]
pub const fn new() -> Self {
Self {
common: crate::OpenOptions::new(),
csum_seed: None,
}
}
#[must_use]
pub const fn base(mut self, base: u64) -> Self {
self.common = self.common.base(base);
self
}
#[must_use]
pub const fn len(mut self, len: u64) -> Self {
self.common = self.common.len(len);
self
}
#[must_use]
pub const fn policy(mut self, policy: ReadPolicy) -> Self {
self.common = self.common.policy(policy);
self
}
#[must_use]
pub const fn limits(mut self, limits: Limits) -> Self {
self.common = self.common.limits(limits);
self
}
#[must_use]
pub const fn common(mut self, common: crate::OpenOptions) -> Self {
self.common = common;
self
}
#[must_use]
pub const fn csum_seed(mut self, seed: u32) -> Self {
self.csum_seed = Some(seed);
self
}
}
impl<R: Read + Seek> Reader<R> {
pub fn open(src: R) -> Result<Self, ReadError> {
Self::open_with(src, &OpenOptions::new())
}
pub fn open_with(src: R, options: &OpenOptions) -> Result<Self, ReadError> {
let &OpenOptions {
common:
crate::OpenOptions {
base,
len,
policy,
limits,
..
},
csum_seed,
} = options;
let mut src = Bounded::new(src, base, len);
let sb_offset = offset_of(base, 1, 1024).ok_or(ReadError::OutOfRange {
what: "bytes",
index: base,
})?;
let sb_bytes = read_exact_at(&mut src, sb_offset, SuperBlock::SIZE)?;
let (sb, feature, block_size) = Self::checked_superblock(&sb_bytes)?;
let unsupported = unsupported_incompat(feature.incompat);
if unsupported != 0 && policy.is_fatal(Severity::Structural) {
return Err(ReadError::UnsupportedIncompat { bits: unsupported });
}
let source_len = src.seek(SeekFrom::End(0))?.saturating_sub(base);
let needs_recovery = sb.feature_incompat & INCOMPAT_RECOVER != 0;
let state_on_disk = sb.state;
let mut reader = Self {
src,
base,
source_len,
sb,
sb_raw: sb_bytes,
feature,
block_size,
policy,
limits,
csum_seed,
table_cache: table_cache(block_size),
needs_recovery,
state_on_disk,
journal: None,
};
if needs_recovery {
reader.recover()?;
}
Ok(reader)
}
fn checked_superblock(sb_bytes: &[u8]) -> Result<(SuperBlock, FeatureSet, usize), ReadError> {
let mut sb = SuperBlock::read_from(sb_bytes)?;
if sb.rev_level == 0 {
sb.inode_size = GOOD_OLD_INODE_SIZE as u16;
sb.first_ino = GOOD_OLD_FIRST_INODE;
}
if sb.log_block_size > 6 {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_log_block_size",
value: u64::from(sb.log_block_size),
}));
}
let block_size = 1024usize << sb.log_block_size;
if !sb.inode_size.is_power_of_two()
|| sb.inode_size < 128
|| usize::from(sb.inode_size) > block_size
{
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_inode_size",
value: u64::from(sb.inode_size),
}));
}
let feature = FeatureSet {
compat: crate::feature::Compat::from_bits(sb.feature_compat),
incompat: Incompat::from_bits(sb.feature_incompat),
ro_compat: crate::feature::RoCompat::from_bits(sb.feature_ro_compat),
block_size: block_size as u32,
inode_size: sb.inode_size,
};
if feature.is_64bit()
&& (!sb.desc_size.is_power_of_two()
|| usize::from(sb.desc_size) < GroupDescriptor::SIZE_64
|| usize::from(sb.desc_size) > block_size)
{
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_desc_size",
value: u64::from(sb.desc_size),
}));
}
let per_group_cap = 8 * block_size as u64;
let blocks_cap = if sb.feature_ro_compat & RO_COMPAT_BIGALLOC != 0 {
per_group_cap
<< sb
.log_cluster_size
.saturating_sub(sb.log_block_size)
.min(30)
} else {
per_group_cap
};
if sb.blocks_per_group == 0 || u64::from(sb.blocks_per_group) > blocks_cap {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_blocks_per_group",
value: u64::from(sb.blocks_per_group),
}));
}
if sb.inodes_per_group == 0 || u64::from(sb.inodes_per_group) > per_group_cap {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_inodes_per_group",
value: u64::from(sb.inodes_per_group),
}));
}
if sb.feature_ro_compat & RO_COMPAT_BIGALLOC != 0 && block_size == 1024 {
return Err(ReadError::UnsupportedLayout {
layout: "bigalloc at a 1024-byte block, whose first data block is 0",
});
}
if sb.first_data_block != u32::from(block_size == 1024) {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_first_data_block",
value: u64::from(sb.first_data_block),
}));
}
if sb.blocks_count <= u64::from(sb.first_data_block) {
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_blocks_count",
value: sb.blocks_count,
}));
}
let groups = (sb.blocks_count - u64::from(sb.first_data_block))
.div_ceil(u64::from(sb.blocks_per_group));
if u64::from(sb.inodes_count) != u64::from(sb.inodes_per_group) * groups
|| sb.inodes_count < ROOT_INO
{
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "superblock",
field: "s_inodes_count",
value: u64::from(sb.inodes_count),
}));
}
Ok((sb, feature, block_size))
}
#[must_use]
pub fn superblock(&self) -> &SuperBlock {
&self.sb
}
#[must_use]
pub fn metadata(&self, inode: &Inode) -> Metadata {
let born = Inode::has_crtime(self.sb.inode_size, inode.extra_isize);
Metadata {
mode: inode.mode & 0o7777,
uid: inode.uid,
gid: inode.gid,
atime: inode.atime,
ctime: inode.ctime,
mtime: inode.mtime,
btime: born.then_some(inode.crtime),
}
}
#[must_use]
pub fn feature(&self) -> FeatureSet {
self.feature
}
#[must_use]
pub fn profile(&self) -> Profile {
Profile::of(self.feature)
}
#[must_use]
pub fn policy(&self) -> ReadPolicy {
self.policy
}
fn read_at(&mut self, offset: u64, len: usize) -> Result<Vec<u8>, ReadError> {
let mut bytes = self.read_home(offset, len)?;
if len > 0 && self.journal.as_ref().is_some_and(|j| !j.overlay.is_empty()) {
self.lay_over(offset, &mut bytes)?;
}
Ok(bytes)
}
fn lay_over(&mut self, offset: u64, bytes: &mut [u8]) -> Result<(), ReadError> {
let bs = self.block_size as u64;
let end = offset.saturating_add(bytes.len() as u64);
let first = offset / bs;
let last = (end - 1) / bs;
let copies: Vec<(u64, crate::replay::Copy)> = self
.journal
.as_ref()
.map(|j| {
j.overlay
.range(first..=last)
.map(|(&home, ©)| (home, copy))
.collect()
})
.unwrap_or_default();
for (home, copy) in copies {
let at = offset_of(0, copy.at, bs).ok_or(ReadError::OutOfRange {
what: "block",
index: copy.at,
})?;
let mut block = self.read_home(at, self.block_size)?;
if copy.escaped {
block[..4].copy_from_slice(&crate::journal::JBD2_MAGIC.to_be_bytes());
}
let home_start = home * bs;
let lo = home_start.max(offset);
let hi = (home_start + bs).min(end);
let (into, from) = ((lo - offset) as usize, (lo - home_start) as usize);
let n = (hi - lo) as usize;
bytes[into..into + n].copy_from_slice(&block[from..from + n]);
}
Ok(())
}
fn read_home(&mut self, offset: u64, len: usize) -> Result<Vec<u8>, ReadError> {
let pos = offset_of(self.base, offset, 1).ok_or(ReadError::OutOfRange {
what: "bytes",
index: offset,
})?;
match read_exact_at(&mut self.src, pos, len) {
Ok(buf) => Ok(buf),
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => Err(ReadError::OutOfRange {
what: "bytes",
index: offset,
}),
Err(e) => Err(ReadError::from(e)),
}
}
fn block(&mut self, block: u64) -> Result<Vec<u8>, ReadError> {
self.check_block(block)?;
let start = offset_of(0, block, self.block_size as u64).ok_or(ReadError::OutOfRange {
what: "block",
index: block,
})?;
match self.read_at(start, self.block_size) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "block",
index: block,
}),
other => other,
}
}
fn blocks_in_reach(&self, first: u64, count: usize) -> bool {
let Some(end) = u64::try_from(count)
.ok()
.and_then(|count| first.checked_add(count))
else {
return false;
};
count > 0
&& end <= self.sb.blocks_count
&& offset_of(0, end, self.block_size as u64).is_some_and(|end| end <= self.source_len)
}
fn table_bytes(&mut self, offset: u64, len: usize) -> Result<Vec<u8>, ReadError> {
let bs = self.block_size as u64;
let block = offset / bs;
let within = usize::try_from(offset % bs).unwrap_or(usize::MAX);
if within.saturating_add(len) > self.block_size || !self.blocks_in_reach(block, 1) {
return self.read_at(offset, len);
}
if let Some(bytes) = self.table_cache.get(block) {
return Ok(bytes[within..within + len].to_vec());
}
let bytes = self.read_at(block * bs, self.block_size)?;
let out = bytes[within..within + len].to_vec();
self.table_cache.insert(block, bytes);
Ok(out)
}
fn read_run(&mut self, run: &Run) -> Result<Option<Vec<u8>>, ReadError> {
if run.phys == 0 || run.len < 2 || !self.blocks_in_reach(run.phys, run.len) {
return Ok(None);
}
let bs = self.block_size as u64;
let start = offset_of(0, run.phys, bs);
let len = offset_of(0, run.len as u64, bs).and_then(|len| usize::try_from(len).ok());
match (start, len) {
(Some(start), Some(len)) => self.read_at(start, len).map(Some),
_ => Ok(None),
}
}
fn max_run_blocks(&self) -> usize {
(MAX_RUN_BYTES / self.block_size.max(1)).max(1)
}
fn recover(&mut self) -> Result<(), ReadError> {
let fault = match self.replay_journal() {
Ok(()) => return Ok(()),
Err(fault) => fault,
};
self.journal = None;
self.table_cache = table_cache(self.block_size);
if self.policy.is_fatal(fault.anomaly().severity) {
return Err(fault);
}
self.journal = Some(Box::new(Recovery {
overlay: BTreeMap::new(),
outcome: Outcome::NotReplayed(fault),
}));
Ok(())
}
fn replay_journal(&mut self) -> Result<(), ReadError> {
let replay = self.plan_replay()?;
let skipped: Vec<ReadError> = replay
.skipped
.iter()
.map(|s| ReadError::JournalCopyChecksum {
block: s.home,
sequence: s.sequence,
stored: s.stored,
computed: s.computed,
})
.collect();
if let Some(first) = skipped.first()
&& self.policy.is_fatal(first.anomaly().severity)
{
return Err(first.clone());
}
let report = JournalReplay {
transactions: replay.transactions,
blocks: replay.copies.len() as u64,
skipped: u32::try_from(skipped.len()).unwrap_or(u32::MAX),
};
self.journal = Some(Box::new(Recovery {
overlay: replay.copies,
outcome: Outcome::Replayed(report, skipped),
}));
self.table_cache = table_cache(self.block_size);
let sb_bytes = self.read_at(1024, SuperBlock::SIZE)?;
let (sb, feature, block_size) = Self::checked_superblock(&sb_bytes)?;
if block_size != self.block_size {
return Err(ReadError::JournalMalformed {
log_block: 0,
detail: "a replayed superblock naming a different block size",
});
}
let unsupported = unsupported_incompat(feature.incompat);
if unsupported != 0 && self.policy.is_fatal(Severity::Structural) {
return Err(ReadError::UnsupportedIncompat { bits: unsupported });
}
self.sb = sb;
self.sb_raw = sb_bytes;
self.feature = feature;
Ok(())
}
fn plan_replay(&mut self) -> Result<crate::replay::Replay, ReadError> {
if !self.feature.has_journal() {
return Err(ReadError::JournalMalformed {
log_block: 0,
detail: "a filesystem needing recovery that has no journal",
});
}
if self.sb.journal_inum == 0 {
return Err(ReadError::JournalUnsupported {
feature: "a journal on another device",
});
}
let inode = self.inode(self.sb.journal_inum)?;
let bs = self.block_size as u64;
let journal_blocks = (self.file_len(&inode) / bs).min(self.materialized_block_bound());
let block_size = self.block_size;
let fs_blocks = self.sb.blocks_count;
let mut log = JournalLog {
reader: self,
inode,
window: None,
};
let superblock = crate::replay::Log::read(&mut log, 0)?;
crate::replay::plan(&superblock, block_size, fs_blocks, journal_blocks, &mut log)
}
#[cfg(test)]
fn with_table_capacity(mut self, capacity: usize) -> Self {
self.table_cache = TableCache::new(capacity);
self
}
pub fn group_descriptor(&mut self, group: u32) -> Result<GroupDescriptor, ReadError> {
let raw = self.group_descriptor_raw(group)?;
Ok(GroupDescriptor::read_from(&raw, self.desc_size())?)
}
fn desc_size(&self) -> usize {
if self.feature.is_64bit() {
debug_assert!(
usize::from(self.sb.desc_size) >= GroupDescriptor::SIZE_64,
"open_with admitted a 64bit image with s_desc_size {}",
self.sb.desc_size
);
self.sb.desc_size.max(GroupDescriptor::SIZE_32 as u16) as usize
} else {
GroupDescriptor::SIZE_32
}
}
fn descriptor_place(&self, group: u32) -> Option<(u64, usize)> {
let desc_size = self.desc_size();
let per_block = u32::try_from(self.block_size / desc_size).ok()?.max(1);
let meta_group = group / per_block;
let within = (group % per_block) as usize * desc_size;
let first_data_block = u64::from(self.sb.first_data_block);
let block = if self.feature.incompat.contains(Incompat::META_BG)
&& meta_group >= self.sb.first_meta_bg
{
let first = meta_group.checked_mul(per_block)?;
let start = offset_of(
first_data_block,
u64::from(first),
u64::from(self.sb.blocks_per_group),
)?;
start.checked_add(u64::from(carries_superblock(first, &self.sb)))?
} else {
first_data_block
.checked_add(1)?
.checked_add(u64::from(meta_group))?
};
Some((block, within))
}
fn group_descriptor_raw(&mut self, group: u32) -> Result<Vec<u8>, ReadError> {
let desc_size = self.desc_size();
let off = self
.descriptor_place(group)
.and_then(|(block, within)| {
offset_of(0, block, self.block_size as u64)?.checked_add(within as u64)
})
.ok_or(ReadError::OutOfRange {
what: "group",
index: u64::from(group),
})?;
let last_block = (off + desc_size as u64 - 1) / self.block_size as u64;
if last_block >= self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "group",
index: u64::from(group),
});
}
match self.table_bytes(off, desc_size) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "group",
index: u64::from(group),
}),
other => other,
}
}
#[must_use]
pub fn group_count(&self) -> u32 {
let bpg = u64::from(self.sb.blocks_per_group);
if bpg == 0 {
return 0;
}
let addressable = self
.sb
.blocks_count
.saturating_sub(u64::from(self.sb.first_data_block));
addressable.div_ceil(bpg).min(u64::from(u32::MAX)) as u32
}
const fn source_len(&self) -> u64 {
self.source_len
}
fn group_in_use_inodes(&mut self, g: u32) -> Result<Vec<u32>, ReadError> {
let desc = self.group_descriptor(g)?;
if desc.flags & BG_INODE_UNINIT != 0 && self.uninit_flags_apply() {
return Ok(Vec::new());
}
let ipg = self.sb.inodes_per_group;
let base = u64::from(g) * u64::from(ipg);
let bmp = self.block(desc.inode_bitmap)?;
let mut out = Vec::new();
for i in 0..ipg {
let byte = (i / 8) as usize;
if byte >= bmp.len() {
break;
}
if bmp[byte] & (1u8 << (i % 8)) == 0 {
continue;
}
let number = base + u64::from(i) + 1;
if number > u64::from(self.sb.inodes_count) {
break;
}
out.push(number as u32);
}
Ok(out)
}
fn bitmap_bits_per_group(&self) -> u32 {
if self.feature.ro_compat.bits() & RO_COMPAT_BIGALLOC != 0 {
self.sb.clusters_per_group
} else {
self.sb.blocks_per_group
}
}
fn uninit_flags_apply(&self) -> bool {
self.feature.has_metadata_csum() || self.feature.ro_compat.bits() & RO_COMPAT_GDT_CSUM != 0
}
fn descriptor_crc16(&self, group: u32, raw: &[u8]) -> Option<u16> {
(!self.feature.has_metadata_csum()
&& self.feature.ro_compat.bits() & RO_COMPAT_GDT_CSUM != 0)
.then(|| recipe::group_descriptor_crc16(&self.sb.uuid, group, raw))
}
fn descriptor_checksum(&self, group: u32, raw: &[u8], csum: &Crc32c) -> u16 {
let mut buf = raw.to_vec();
put_u16(&mut buf, GroupDescriptor::CHECKSUM_OFFSET, 0);
recipe::group_descriptor(csum, group, &buf)
}
fn inode_checksum(&self, number: u32, raw: &[u8], csum: &Crc32c) -> (u32, u32) {
let inode_size = self.sb.inode_size;
let extra_isize = if usize::from(inode_size) > GOOD_OLD_INODE_SIZE {
get_u16(raw, 0x80)
} else {
0
};
let has_hi = Inode::has_checksum_hi(inode_size, extra_isize);
let mut buf = raw.to_vec();
put_u16(&mut buf, Inode::CHECKSUM_LO_OFFSET, 0);
let stored = {
let lo = u32::from(get_u16(raw, Inode::CHECKSUM_LO_OFFSET));
if has_hi {
put_u16(&mut buf, Inode::CHECKSUM_HI_OFFSET, 0);
lo | (u32::from(get_u16(raw, Inode::CHECKSUM_HI_OFFSET)) << 16)
} else {
lo
}
};
let generation = get_u32(raw, 0x64);
let computed = recipe::inode(csum, number, generation, &buf, has_hi);
(stored, computed)
}
pub fn verify_checksums(&mut self) -> Result<(), ReadError> {
if !self.feature.has_metadata_csum() {
for g in 0..self.group_count() {
let raw = self.group_descriptor_raw(g)?;
if let Some(computed) = self.descriptor_crc16(g, &raw) {
let desc = GroupDescriptor::read_from(&raw, self.desc_size())?;
check_checksum(
"group descriptor",
u64::from(g),
u32::from(desc.checksum),
u32::from(computed),
)?;
}
}
return Ok(());
}
let csum = self.checksummer();
let computed = superblock_checksum(&self.sb_raw);
check_checksum("superblock", 0, self.sb.checksum, computed)?;
for g in 0..self.group_count() {
let raw = self.group_descriptor_raw(g)?;
let desc = GroupDescriptor::read_from(&raw, self.desc_size())?;
let computed = self.descriptor_checksum(g, &raw, &csum);
check_checksum(
"group descriptor",
u64::from(g),
u32::from(desc.checksum),
u32::from(computed),
)?;
self.verify_bitmap_checksums(g, &csum)?;
}
let max_inodes = self.source_len() / u64::from(self.sb.inode_size.max(128));
let mut examined = 0u64;
'inodes: for g in 0..self.group_count() {
for n in self.group_in_use_inodes(g)? {
if examined >= max_inodes {
break 'inodes;
}
examined += 1;
let raw = self.inode_raw(n)?;
let mut inode = Inode::read_from(&raw, self.sb.inode_size)?;
self.mask_ungated_halves(&mut inode, &raw);
let (stored, computed) = self.inode_checksum(n, &raw, &csum);
check_checksum("inode", u64::from(n), stored, computed)?;
self.verify_extent_nodes(n, &inode, &csum)?;
self.verify_directory_checksums(n, &inode, &csum)?;
self.verify_xattr_block_checksum(&inode, &csum)?;
}
}
self.journal_superblock()?;
self.verify_orphan_blocks(&csum)?;
let mut mmp_faults = Vec::new();
self.collect_mmp_faults(&csum, &mut mmp_faults);
mmp_faults
.into_iter()
.find(|e| !matches!(e, ReadError::MmpInUse { .. }))
.map_or(Ok(()), Err)
}
fn collect_mmp_faults(&mut self, csum: &Crc32c, faults: &mut Vec<ReadError>) {
if self.feature.incompat.bits() & INCOMPAT_MMP == 0 {
return;
}
let block = self.sb.mmp_block;
if block < u64::from(self.sb.first_data_block) || block >= self.sb.blocks_count {
faults.push(ReadError::OutOfRange {
what: "multiple-mount protection block",
index: block,
});
return;
}
let bytes = match self.block(block) {
Ok(bytes) => bytes,
Err(e) => {
faults.push(e);
return;
}
};
let record = Mmp::read_from(&bytes);
if record.magic != MMP_MAGIC {
faults.push(ReadError::BadMmpBlock { block });
return;
}
if self.feature.has_metadata_csum() {
let computed = recipe::mmp_block(csum, &bytes);
if computed != record.checksum {
faults.push(ReadError::ChecksumMismatch {
object: "multiple-mount protection block",
index: block,
stored: record.checksum,
computed,
});
}
}
if record.sequence != MMP_SEQ_CLEAN {
faults.push(ReadError::MmpInUse {
sequence: record.sequence,
});
}
}
fn checksummer(&self) -> Crc32c {
match self.csum_seed {
Some(seed) => Crc32c::with_seed(seed),
None if self.feature.has_csum_seed() => Crc32c::with_seed(self.sb.checksum_seed),
None => Crc32c::new(&self.sb.uuid),
}
}
fn verify_orphan_blocks(&mut self, csum: &Crc32c) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_orphan_faults(csum, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_orphan_faults(&mut self, csum: &Crc32c, faults: &mut Vec<ReadError>) {
if !self.feature.has_orphan_file() {
return;
}
let has_csum = self.feature.has_metadata_csum();
let ino = self.sb.orphan_file_inum;
if ino == 0 {
faults.push(ReadError::BadOrphanFile);
return;
}
let inode = match self.inode(ino) {
Ok(inode) => inode,
Err(e) => {
faults.push(e);
return;
}
};
let generation = inode.generation;
let bound = self.materialized_block_bound();
if inode.size.div_ceil(self.block_size as u64) > bound {
faults.push(ReadError::BadOrphanFile);
return;
}
let blocks = match self.data_blocks(&inode) {
Ok(blocks) => blocks,
Err(e) => {
faults.push(e);
return;
}
};
for phys in blocks {
if phys == 0 {
faults.push(ReadError::BadOrphanFile);
continue;
}
let block = match self.block(phys) {
Ok(block) => block,
Err(e) => {
faults.push(e);
continue;
}
};
let stored = match read_orphan_tail(&block) {
Ok(stored) => stored,
Err(_) => {
faults.push(ReadError::BadOrphanFile);
continue;
}
};
if !has_csum {
continue; }
let entries = &block[..orphan_entries_len(block.len())];
let c = recipe::orphan_block(csum, ino, generation, phys, entries);
if c != stored {
faults.push(ReadError::ChecksumMismatch {
object: "orphan block",
index: phys,
stored,
computed: c,
});
}
}
}
fn verify_extent_nodes(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
) -> Result<(), ReadError> {
if !inode.flags.contains(InodeFlags::EXTENTS) {
return Ok(());
}
let seed = recipe::inode_seed(csum, ino, inode.generation);
let mut visited = HashSet::new();
self.verify_extent_subtree(&inode.block, 0, seed, csum, &mut visited)
}
fn verify_extent_subtree(
&mut self,
node: &[u8],
depth: u16,
seed: u32,
csum: &Crc32c,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
if depth > MAX_EXTENT_DEPTH {
return Err(ReadError::BadExtentTree);
}
let ExtentNode::Index { entries, .. } = parse_node(node)? else {
return Ok(());
};
for idx in entries {
if !visited.insert(idx.leaf) {
return Err(ReadError::BadExtentTree);
}
let child = self.block(idx.leaf)?;
let tail = extent_tail_offset(&child, self.block_size);
let stored = u32::from_le_bytes(
child[tail..tail + EXTENT_TAIL_LEN]
.try_into()
.expect("tail slice is exactly EXTENT_TAIL_LEN bytes"),
);
let computed = csum.crc32c(seed, &child[..tail]);
check_checksum("extent node", idx.leaf, stored, computed)?;
self.verify_extent_subtree(&child, depth + 1, seed, csum, visited)?;
}
Ok(())
}
fn collect_metadata_placement_faults(
&self,
g: u32,
desc: &GroupDescriptor,
faults: &mut Vec<ReadError>,
) {
if self.feature.has_flex_bg() {
return;
}
let bpg = u64::from(self.sb.blocks_per_group);
if bpg == 0 {
return;
}
let start = u64::from(self.sb.first_data_block) + u64::from(g) * bpg;
let end = start.saturating_add(bpg).min(self.sb.blocks_count);
let in_group = |block: u64| block >= start && block < end;
for (what, block) in [
("block bitmap", desc.block_bitmap),
("inode bitmap", desc.inode_bitmap),
("inode table", desc.inode_table),
] {
if !in_group(block) {
faults.push(ReadError::MetadataOutsideGroup {
what,
group: g,
block,
});
}
}
}
fn verify_bitmap_checksums(&mut self, g: u32, csum: &Crc32c) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_bitmap_faults(g, csum, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_bitmap_faults(&mut self, g: u32, csum: &Crc32c, faults: &mut Vec<ReadError>) {
let desc = match self.group_descriptor(g) {
Ok(desc) => desc,
Err(e) => {
faults.push(e);
return;
}
};
let wide = self.desc_size() >= GroupDescriptor::SIZE_64;
let fold = |c: u32| if wide { c } else { c & 0xffff };
if desc.flags & BG_BLOCK_UNINIT == 0 {
let len = recipe::block_bitmap_len(self.bitmap_bits_per_group());
match self.block(desc.block_bitmap) {
Ok(bmp) => {
let computed = fold(recipe::bitmap(csum, &bmp[..len.min(bmp.len())]));
if computed != desc.block_bitmap_csum {
faults.push(ReadError::ChecksumMismatch {
object: "block bitmap",
index: u64::from(g),
stored: desc.block_bitmap_csum,
computed,
});
}
}
Err(e) => faults.push(e),
}
}
if desc.flags & BG_INODE_UNINIT == 0 {
let len = recipe::inode_bitmap_len(self.sb.inodes_per_group);
match self.block(desc.inode_bitmap) {
Ok(bmp) => {
let computed = fold(recipe::bitmap(csum, &bmp[..len.min(bmp.len())]));
if computed != desc.inode_bitmap_csum {
faults.push(ReadError::ChecksumMismatch {
object: "inode bitmap",
index: u64::from(g),
stored: desc.inode_bitmap_csum,
computed,
});
}
}
Err(e) => faults.push(e),
}
}
}
fn verify_directory_checksums(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
) -> Result<(), ReadError> {
let mut faults = Vec::new();
self.collect_directory_faults(ino, inode, csum, &mut faults);
faults.into_iter().next().map_or(Ok(()), Err)
}
fn collect_directory_faults(
&mut self,
ino: u32,
inode: &Inode,
csum: &Crc32c,
faults: &mut Vec<ReadError>,
) {
if inode.mode & 0o170000 != 0o040000 {
return;
}
let indexed = inode.flags.contains(InodeFlags::INDEX);
let base = recipe::inode_seed(csum, ino, inode.generation);
let blocks = match self.data_blocks(inode) {
Ok(blocks) => blocks,
Err(e) => {
faults.push(e);
return;
}
};
let (root_indexed, interior) = match self.directory_index_layout(&blocks, indexed) {
Ok(layout) => layout,
Err(e) => {
faults.push(e);
return;
}
};
let mut checked = HashSet::new();
for (logical, &phys) in blocks.iter().enumerate() {
if phys == 0 {
continue;
}
if !checked.insert(phys) {
continue;
}
let logical = logical as u64;
let block = match self.block(phys) {
Ok(block) => block,
Err(e) => {
faults.push(e);
continue;
}
};
let count_offset = if logical == 0 && root_indexed {
Some(DX_ROOT_COUNT_OFFSET)
} else if interior.contains(&logical) {
Some(DX_NODE_COUNT_OFFSET)
} else {
None
};
if let Err(e) = self.verify_one_dir_block(phys, &block, base, count_offset, csum) {
faults.push(e);
}
}
}
fn directory_index_layout(
&mut self,
blocks: &[u64],
indexed: bool,
) -> Result<(bool, HashSet<u64>), ReadError> {
let mut interior = HashSet::new();
if !indexed {
return Ok((false, interior));
}
let Some(root_phys) = blocks.first().copied().filter(|&b| b != 0) else {
return Ok((false, interior));
};
let root = self.block(root_phys)?;
let levels = match read_dx_root_info(&root) {
Ok((_, levels)) => levels,
Err(_) => return Ok((true, interior)),
};
let mut frontier = vec![0u64];
for _ in 0..levels {
let mut next = Vec::new();
for &logical in &frontier {
let Some(phys) = blocks.get(logical as usize).copied().filter(|&b| b != 0) else {
continue;
};
let block = self.block(phys)?;
let count_offset = if logical == 0 {
DX_ROOT_COUNT_OFFSET
} else {
DX_NODE_COUNT_OFFSET
};
let Ok(entries) = read_dx_entries(&block, count_offset) else {
continue;
};
for entry in entries {
let child = u64::from(entry.block);
if child != 0 && (child as usize) < blocks.len() && interior.insert(child) {
next.push(child);
}
}
}
frontier = next;
}
Ok((true, interior))
}
fn verify_one_dir_block(
&self,
phys: u64,
block: &[u8],
base: u32,
count_offset: Option<usize>,
csum: &Crc32c,
) -> Result<(), ReadError> {
match count_offset {
None => {
if block.len() < DIR_TAIL_LEN + 4 {
return Ok(());
}
let covered = block.len() - DIR_TAIL_LEN;
let computed = csum.crc32c(base, &block[..covered]);
let stored = get_u32(block, block.len() - 4);
check_checksum("directory block", phys, stored, computed)?;
}
Some(count_offset) => {
let limit = usize::from(get_u16(block, count_offset));
let count = usize::from(get_u16(block, count_offset + 2));
let covered = count_offset + DX_ENTRY_LEN * count;
let tail = dx_tail_offset(count_offset, limit);
if covered > block.len() || tail + DX_TAIL_LEN > block.len() {
let (field, value) = if tail + DX_TAIL_LEN > block.len() {
("limit", limit)
} else {
("count", count)
};
return Err(ReadError::Parse(ParseError::InvalidField {
structure: "DxCountLimit",
field,
value: value as u64,
}));
}
let mut c = csum.crc32c(base, &block[..covered]);
c = csum.crc32c(c, &block[tail..tail + DX_CHECKSUM_OFFSET]);
c = csum.crc32c(c, &[0u8; DX_TAIL_LEN - DX_CHECKSUM_OFFSET]);
let stored = get_u32(block, tail + 4);
check_checksum("directory block", phys, stored, c)?;
}
}
Ok(())
}
fn verify_xattr_block_checksum(
&mut self,
inode: &Inode,
csum: &Crc32c,
) -> Result<(), ReadError> {
let phys = inode.file_acl;
if phys == 0 {
return Ok(());
}
let mut block = self.block(phys)?;
if block.len() < 20 {
return Ok(());
}
let stored = get_u32(&block, XATTR_CHECKSUM_OFFSET);
crate::ondisk::put_u32(&mut block, XATTR_CHECKSUM_OFFSET, 0);
let c = recipe::xattr_block(csum, phys, &block);
check_checksum("xattr block", phys, stored, c)?;
Ok(())
}
#[must_use]
pub fn scan(&mut self) -> ScanReport {
let mut anomalies = Findings::new(self.limits.max_findings);
let has_csum = self.feature.has_metadata_csum();
let csum = self.checksummer();
let source_len = self.source_len();
let block_size = self.block_size as u64;
let max_blocks = source_len / block_size;
if self.sb.blocks_count > max_blocks {
anomalies.push(
ReadError::SourceTooShort {
blocks: self.sb.blocks_count,
held: max_blocks,
}
.anomaly(),
);
}
let unsupported = unsupported_incompat(self.feature.incompat);
if unsupported != 0 {
anomalies.push(ReadError::UnsupportedIncompat { bits: unsupported }.anomaly());
}
match self.journal.as_deref().map(|j| &j.outcome) {
None => {}
Some(Outcome::Replayed(_, skipped)) => {
for fault in skipped {
anomalies.push(fault.anomaly());
}
}
Some(Outcome::NotReplayed(fault)) => anomalies.push(fault.anomaly()),
}
for state in self.left_state() {
anomalies.push(state.anomaly());
}
if has_csum {
let computed = superblock_checksum(&self.sb_raw);
if computed != self.sb.checksum {
anomalies.push(
ReadError::ChecksumMismatch {
object: "superblock",
index: 0,
stored: self.sb.checksum,
computed,
}
.anomaly(),
);
}
}
let bpg = u64::from(self.sb.blocks_per_group.max(1));
let group_bound = (max_blocks / bpg)
.saturating_add(2)
.min(u64::from(u32::MAX)) as u32;
let desc_size = self.desc_size();
let mut uninit_groups = HashSet::new();
for g in 0..self.group_count().min(group_bound) {
if anomalies.is_full() {
break;
}
let raw = match self.group_descriptor_raw(g) {
Err(e) => {
anomalies.push(e.anomaly());
continue;
}
Ok(raw) => raw,
};
match GroupDescriptor::read_from(&raw, desc_size) {
Err(e) => anomalies.push(ReadError::Parse(e).anomaly()),
Ok(desc) => {
let mut placement = Vec::new();
self.collect_metadata_placement_faults(g, &desc, &mut placement);
for e in &placement {
anomalies.push(e.anomaly());
}
let uninit = desc.flags & (BG_INODE_UNINIT | BG_BLOCK_UNINIT);
if uninit != 0 && !self.uninit_flags_apply() {
anomalies.push(
ReadError::UninitFlagWithoutFeature {
group: g,
flags: uninit,
}
.anomaly(),
);
}
if desc.flags & BG_INODE_UNINIT != 0 && self.uninit_flags_apply() {
uninit_groups.insert(g);
}
if let Some(computed) = self.descriptor_crc16(g, &raw)
&& computed != desc.checksum
{
anomalies.push(
ReadError::ChecksumMismatch {
object: "group descriptor",
index: u64::from(g),
stored: u32::from(desc.checksum),
computed: u32::from(computed),
}
.anomaly(),
);
}
if has_csum {
let computed = self.descriptor_checksum(g, &raw, &csum);
if computed != desc.checksum {
anomalies.push(
ReadError::ChecksumMismatch {
object: "group descriptor",
index: u64::from(g),
stored: u32::from(desc.checksum),
computed: u32::from(computed),
}
.anomaly(),
);
}
let mut faults = Vec::new();
self.collect_bitmap_faults(g, &csum, &mut faults);
for e in &faults {
anomalies.push(anomaly_in_bitmap(e, g, Category::Bitmap));
}
}
}
}
}
let max_inodes = source_len / u64::from(self.sb.inode_size.max(128));
let mut visited = HashSet::new();
let mut judged = HashSet::new();
if uninit_groups.contains(&((ROOT_INO - 1) / self.sb.inodes_per_group.max(1))) {
anomalies.push(anomaly_at_inode(
&ReadError::InodeInUninitGroup { inode: ROOT_INO },
ROOT_INO,
));
}
let dir_budget = self.materialized_block_bound();
let mut dir_blocks = 0u64;
let mut outspent = false;
let inode_size = self.sb.inode_size;
let mut examined = 0u64;
'inodes: for g in 0..self.group_count().min(group_bound) {
if examined >= max_inodes {
break;
}
if anomalies.is_full() {
break;
}
let in_use = match self.group_in_use_inodes(g) {
Ok(v) => v,
Err(e) => {
anomalies.push(anomaly_in_bitmap(&e, g, Category::Bitmap));
continue;
}
};
for n in in_use {
if examined >= max_inodes {
break 'inodes;
}
if anomalies.is_full() {
break 'inodes;
}
examined += 1;
let raw = match self.inode_raw(n) {
Err(e) => {
anomalies.push(anomaly_at_inode(&e, n));
continue;
}
Ok(raw) => raw,
};
match Inode::read_from(&raw, inode_size) {
Err(e) => anomalies.push(anomaly_at_inode(&ReadError::Parse(e), n)),
Ok(mut inode) => {
self.mask_ungated_halves(&mut inode, &raw);
if has_csum {
let (stored, computed) = self.inode_checksum(n, &raw, &csum);
if computed != stored {
anomalies.push(
ReadError::ChecksumMismatch {
object: "inode",
index: u64::from(n),
stored,
computed,
}
.anomaly(),
);
}
}
self.scan_feature_coherence(n, &inode, &mut anomalies);
self.scan_stored_values(n, &inode, &mut anomalies);
self.scan_inode_map(
n,
&inode,
has_csum,
&csum,
&mut visited,
&mut anomalies,
);
let walk_content = !(outspent && is_dir(&inode));
if is_dir(&inode) && !is_inline(&inode) && !outspent {
dir_blocks =
dir_blocks.saturating_add(self.logical_block_count(&inode) as u64);
if dir_blocks > dir_budget {
outspent = true;
anomalies
.push(ReadError::DirectoryBlocksShared { inode: n }.anomaly());
}
}
if walk_content {
self.scan_dirents(n, &inode, has_csum, &uninit_groups, &mut anomalies);
}
if is_dir(&inode) && walk_content {
self.scan_index(n, &inode, &mut judged, &mut anomalies);
}
if has_csum {
let mut faults = Vec::new();
if walk_content {
self.collect_directory_faults(n, &inode, &csum, &mut faults);
}
for e in &faults {
anomalies.push(anomaly_in_mapping(e, n, Category::Directory));
}
if let Err(e) = self.verify_xattr_block_checksum(&inode, &csum) {
anomalies.push(anomaly_in_mapping(&e, n, Category::Xattr));
}
}
}
}
}
}
if let Err(e) = self.journal_superblock() {
anomalies.push(e.anomaly());
}
let mut orphan_faults = Vec::new();
self.collect_orphan_faults(&csum, &mut orphan_faults);
let orphan_ino = self.sb.orphan_file_inum;
for e in &orphan_faults {
anomalies.push(anomaly_in_mapping(e, orphan_ino, Category::Orphan));
}
let mut mmp_faults = Vec::new();
self.collect_mmp_faults(&csum, &mut mmp_faults);
for e in &mmp_faults {
anomalies.push(e.anomaly());
}
anomalies.into_report(self.block_size as u32)
}
fn scan_inode_map(
&mut self,
ino: u32,
inode: &Inode,
has_csum: bool,
csum: &Crc32c,
visited: &mut HashSet<u64>,
out: &mut Findings<Anomaly>,
) {
if !inode.flags.contains(InodeFlags::EXTENTS) {
if !maps_data(inode) {
return;
}
if let Err(e) = self.scan_block_map(inode, visited) {
let owner = if is_dir(inode) {
Category::Directory
} else {
Category::Inode
};
out.push(anomaly_in_mapping(&e, ino, owner));
}
return;
}
let ctx = ExtentScanCtx {
ino,
seed: recipe::inode_seed(csum, ino, inode.generation),
has_csum,
csum,
};
let mut own = HashSet::new();
self.scan_extent_node(
&ctx,
&inode.block,
0,
&(0..u64::MAX),
&mut own,
visited,
out,
);
}
fn scan_feature_coherence(&self, ino: u32, inode: &Inode, out: &mut Findings<Anomaly>) {
if inode.flags.contains(InodeFlags::EXTENTS) && !self.feature.has_extents() {
out.push(ReadError::ExtentFlagWithoutFeature { inode: ino }.anomaly());
}
if inode.file_acl != 0 && !self.feature.has_ext_attr() {
out.push(
ReadError::XattrBlockWithoutFeature {
inode: ino,
block: inode.file_acl,
}
.anomaly(),
);
}
if is_regular(inode) && inode.size >= LARGE_FILE_MIN_SIZE && !self.feature.has_large_file()
{
out.push(
ReadError::LargeFileWithoutFeature {
inode: ino,
size: inode.size,
}
.anomaly(),
);
}
if inode.flags.contains(InodeFlags::INDEX) {
if is_dir(inode) {
if !self.feature.has_dir_index() {
out.push(ReadError::IndexFlagWithoutFeature { inode: ino }.anomaly());
}
} else {
out.push(ReadError::IndexFlagOnNonDirectory { inode: ino }.anomaly());
}
}
}
fn scan_stored_values(&mut self, ino: u32, inode: &Inode, out: &mut Findings<Anomaly>) {
if let Err(
e @ (ReadError::MalformedAcl { .. }
| ReadError::BadValueInode { .. }
| ReadError::BadInlineData { .. }),
) = self.check_stored_values(inode)
{
out.push(anomaly_at_inode(&e, ino));
}
if is_inline(inode)
&& !is_dir(inode)
&& let Err(e) = self.inline_content(inode)
{
out.push(anomaly_at_inode(&e, ino));
}
}
fn check_stored_values(&mut self, inode: &Inode) -> Result<(), ReadError> {
for entry in self.stored_xattrs(inode)? {
if entry.is_the_formats() {
continue;
}
let is_acl = entry.name == Acl::ACCESS_NAME || entry.name == Acl::DEFAULT_NAME;
let value = match entry.value {
XattrValue::Here(value) => value,
XattrValue::InInode { inode, size } if is_acl => {
self.value_in_inode(inode, size)?
}
XattrValue::InInode { inode, size } => {
self.value_inode(inode, size)?;
continue;
}
};
if is_acl {
crate::ondisk::decode_acl(&value).map_err(|source| ReadError::MalformedAcl {
name: entry.name.clone(),
source,
})?;
}
}
Ok(())
}
fn scan_dirents(
&mut self,
ino: u32,
inode: &Inode,
has_csum: bool,
uninit_groups: &HashSet<u32>,
out: &mut Findings<Anomaly>,
) {
if !is_dir(inode) {
return;
}
let Ok(blocks) = self.data_blocks(inode) else {
return;
};
let inline = if is_inline(inode) {
match inline_dir_regions(inode) {
Ok(regions) => Some(regions),
Err(e) => {
out.push(anomaly_at_inode(&e, ino));
return;
}
}
} else {
None
};
let count = inline
.as_ref()
.map_or(blocks.len(), |regions| regions.len());
let mut read = HashSet::new();
let names = Names::of(inode);
let (mut bad_name, mut bad_reference, mut bad_framing) = (false, false, false);
for k in 0..count {
let read_block = match &inline {
Some(regions) => Ok(regions[k].clone()),
None => {
let phys = blocks[k];
if phys == 0 || !read.insert(phys) {
continue;
}
self.block(phys)
}
};
let block = match read_block {
Ok(block) => block,
Err(e) => {
if !bad_framing && !has_csum {
out.push(anomaly_in_mapping(&e, ino, Category::Directory));
bad_framing = true;
}
continue;
}
};
let mut on_fault = |kind: RecordFault, e: ReadError| {
let named = match kind {
RecordFault::Framing => &mut bad_framing,
RecordFault::Name => &mut bad_name,
RecordFault::Reference => &mut bad_reference,
};
if !*named {
out.push(anomaly_at_inode(&e, ino));
*named = true;
}
Ok(())
};
let _ = self.for_each_entry_in_block(
&block,
names,
Some(uninit_groups),
&mut on_fault,
&mut |_| Ok(std::ops::ControlFlow::Continue(())),
);
if bad_name && bad_reference && bad_framing {
return;
}
}
}
#[allow(clippy::too_many_arguments)]
fn scan_extent_node(
&mut self,
ctx: &ExtentScanCtx,
node: &[u8],
depth: u16,
range: &std::ops::Range<u64>,
own: &mut HashSet<u64>,
visited: &mut HashSet<u64>,
out: &mut Findings<Anomaly>,
) {
if depth > MAX_EXTENT_DEPTH {
out.push(anomaly_at_inode(&ReadError::BadExtentTree, ctx.ino));
return;
}
let parsed = match parse_node(node) {
Ok(n) => n,
Err(e) => {
out.push(anomaly_at_inode(&ReadError::Parse(e), ctx.ino));
return;
}
};
if !parsed.holds_range(range) {
out.push(anomaly_at_inode(&ReadError::BadExtentTree, ctx.ino));
return;
}
match parsed {
ExtentNode::Leaves(leaves) => {
for leaf in leaves {
let end = leaf.start.saturating_add(u64::from(leaf.len));
if leaf.start >= self.sb.blocks_count || end > self.sb.blocks_count {
out.push(anomaly_in_mapping(
&ReadError::OutOfRange {
what: "block",
index: leaf.start,
},
ctx.ino,
Category::ExtentTree,
));
}
}
}
ExtentNode::Index { entries, .. } => {
for (at, idx) in entries.iter().enumerate() {
if !own.insert(idx.leaf) {
out.push(anomaly_at_inode(&ReadError::BadExtentTree, ctx.ino));
return;
}
if !visited.insert(idx.leaf) {
continue;
}
let lo = u64::from(idx.block);
let hi = entries
.get(at + 1)
.map_or(range.end, |next| u64::from(next.block));
let child = match self.block(idx.leaf) {
Ok(c) => c,
Err(e) => {
out.push(anomaly_in_mapping(&e, ctx.ino, Category::ExtentTree));
continue;
}
};
if ctx.has_csum {
let tail = extent_tail_offset(&child, self.block_size);
let stored = u32::from_le_bytes(
child[tail..tail + EXTENT_TAIL_LEN]
.try_into()
.expect("tail slice is exactly EXTENT_TAIL_LEN bytes"),
);
let computed = ctx.csum.crc32c(ctx.seed, &child[..tail]);
if stored != computed {
out.push(anomaly_at_inode(
&ReadError::ChecksumMismatch {
object: "extent node",
index: idx.leaf,
stored,
computed,
},
ctx.ino,
));
}
}
self.scan_extent_node(ctx, &child, depth + 1, &(lo..hi), own, visited, out);
}
}
}
}
pub fn inode(&mut self, number: u32) -> Result<Inode, ReadError> {
let raw = self.inode_raw(number)?;
let mut inode = Inode::read_from(&raw, self.sb.inode_size)?;
self.mask_ungated_halves(&mut inode, &raw);
Ok(inode)
}
fn mask_ungated_halves(&self, inode: &mut Inode, raw: &[u8]) {
if self.feature.incompat.bits() & INCOMPAT_LARGEDIR != 0 && is_dir(inode) {
inode.size |= u64::from(get_u32(raw, 0x6c)) << 32;
}
if !self.feature.has_huge_file() {
inode.blocks &= u64::from(u32::MAX);
} else if inode.flags.contains(InodeFlags::HUGE_FILE) {
inode.blocks = inode.blocks.saturating_mul(self.block_size as u64 / 512);
}
if !self.feature.is_64bit() {
inode.file_acl &= u64::from(u32::MAX);
}
}
fn inode_raw(&mut self, number: u32) -> Result<Vec<u8>, ReadError> {
if number == 0 || number > self.sb.inodes_count {
return Err(ReadError::NoSuchInode { inode: number });
}
let ipg = self.sb.inodes_per_group;
if ipg == 0 {
return Err(ReadError::NoSuchInode { inode: number });
}
let group = (number - 1) / ipg;
let index = u64::from((number - 1) % ipg);
let desc = self.group_descriptor(group)?;
let isize = self.sb.inode_size as usize;
let off = offset_of(
index * isize as u64,
desc.inode_table,
self.block_size as u64,
)
.ok_or(ReadError::OutOfRange {
what: "inode",
index: u64::from(number),
})?;
let last_block = off.saturating_add(isize as u64 - 1) / self.block_size as u64;
if last_block >= self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "inode",
index: u64::from(number),
});
}
match self.table_bytes(off, isize) {
Err(ReadError::OutOfRange { .. }) => Err(ReadError::OutOfRange {
what: "inode",
index: u64::from(number),
}),
other => other,
}
}
#[cfg(test)]
fn extent_leaves(
&mut self,
inode: &Inode,
) -> Result<Vec<crate::ondisk::ExtentLeaf>, ReadError> {
self.extent_leaves_in(inode, 0..u64::MAX)
}
fn extent_leaves_in(
&mut self,
inode: &Inode,
window: std::ops::Range<u64>,
) -> Result<Vec<crate::ondisk::ExtentLeaf>, ReadError> {
let mut leaves = Vec::new();
let mut visited = HashSet::new();
self.walk_extent_node(
&inode.block,
0,
&(0..u64::MAX),
&window,
&mut visited,
&mut leaves,
)?;
Ok(leaves)
}
fn walk_extent_node(
&mut self,
node: &[u8],
depth: u16,
range: &std::ops::Range<u64>,
window: &std::ops::Range<u64>,
visited: &mut HashSet<u64>,
out: &mut Vec<crate::ondisk::ExtentLeaf>,
) -> Result<(), ReadError> {
if depth > MAX_EXTENT_DEPTH {
return Err(ReadError::BadExtentTree);
}
let parsed = parse_node(node)?;
if !parsed.holds_range(range) {
return Err(ReadError::BadExtentTree);
}
match parsed {
ExtentNode::Leaves(leaves) => {
for leaf in &leaves {
let end = leaf.start.saturating_add(u64::from(leaf.len));
if leaf.start >= self.sb.blocks_count || end > self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "block",
index: leaf.start,
});
}
}
out.extend(leaves.into_iter().filter(|leaf| {
let lo = u64::from(leaf.block);
let hi = lo.saturating_add(u64::from(leaf.len));
hi > window.start && lo < window.end
}));
}
ExtentNode::Index { entries, .. } => {
for (at, idx) in entries.iter().enumerate() {
let lo = u64::from(idx.block);
let hi = entries
.get(at + 1)
.map_or(range.end, |next| u64::from(next.block));
if !visited.insert(idx.leaf) {
return Err(ReadError::BadExtentTree);
}
if hi <= window.start || lo >= window.end {
continue;
}
let child = self.block(idx.leaf)?;
self.walk_extent_node(&child, depth + 1, &(lo..hi), window, visited, out)?;
}
}
}
Ok(())
}
fn check_block(&self, block: u64) -> Result<(), ReadError> {
if block >= self.sb.blocks_count {
return Err(ReadError::OutOfRange {
what: "block",
index: block,
});
}
Ok(())
}
fn check_dir_entry_inode(&self, inode: u32) -> Result<(), ReadError> {
if inode > self.sb.inodes_count {
return Err(ReadError::DirEntryNoSuchInode { inode });
}
Ok(())
}
fn data_blocks(&mut self, inode: &Inode) -> Result<Vec<u64>, ReadError> {
if is_inline(inode) {
return Ok(Vec::new());
}
let want = self.logical_block_count(inode);
self.map_window(inode, 0, want)
}
fn materialized_block_bound(&mut self) -> u64 {
self.sb
.blocks_count
.min(self.source_len() / self.block_size as u64)
}
fn logical_block_count(&mut self, inode: &Inode) -> usize {
let want = usize::try_from(
inode
.size
.div_ceil(self.block_size as u64)
.min(MAX_LOGICAL_BLOCKS),
)
.unwrap_or(usize::MAX);
if is_dir(inode) {
let bound = self.materialized_block_bound();
return want.min(usize::try_from(bound).unwrap_or(usize::MAX));
}
want
}
fn map_window(
&mut self,
inode: &Inode,
first: usize,
count: usize,
) -> Result<Vec<u64>, ReadError> {
if count == 0 || !maps_data(inode) {
return Ok(Vec::new());
}
let mut map = vec![0u64; count];
if inode.flags.contains(InodeFlags::EXTENTS) {
self.extent_window(inode, first, &mut map)?;
} else {
self.block_map_window(inode, first, &mut map)?;
}
Ok(map)
}
fn extent_window(
&mut self,
inode: &Inode,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
let end = first.saturating_add(map.len());
let window = first as u64..end as u64;
for leaf in self.extent_leaves_in(inode, window)? {
let lo = leaf.block as usize;
let hi = lo.saturating_add(leaf.len as usize);
if hi <= first || lo >= end || !leaf.initialized {
continue;
}
for logical in lo.max(first)..hi.min(end) {
map[logical - first] = leaf.start + (logical - lo) as u64;
}
}
Ok(())
}
fn block_map_window(
&mut self,
inode: &Inode,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
let end = first.saturating_add(map.len());
for i in first..DIRECT_BLOCKS.min(end) {
let ptr = u64::from(get_u32(&inode.block, i * 4));
if ptr != 0 {
self.check_block(ptr)?;
}
map[i - first] = ptr;
}
let per_block = self.block_size / 4;
let mut base = DIRECT_BLOCKS;
for level in 1..=INDIRECT_LEVELS {
if base >= end {
break;
}
let next = base.saturating_add(per_block.saturating_pow(level));
if next > first {
let slot = DIRECT_BLOCKS + level as usize - 1;
let root = u64::from(get_u32(&inode.block, slot * 4));
self.walk_indirect_window(root, level, base, first, map)?;
}
base = next;
}
Ok(())
}
fn walk_indirect_window(
&mut self,
block: u64,
level: u32,
base: usize,
first: usize,
map: &mut [u64],
) -> Result<(), ReadError> {
if block == 0 {
return Ok(());
}
let buf = self.block(block)?;
let per_block = self.block_size / 4;
let span = per_block.saturating_pow(level - 1);
let end = first.saturating_add(map.len());
for i in 0..per_block {
let lo = base.saturating_add(i.saturating_mul(span));
if lo >= end {
break;
}
if lo.saturating_add(span) <= first {
continue;
}
let ptr = u64::from(get_u32(&buf, i * 4));
if level == 1 {
if ptr != 0 {
self.check_block(ptr)?;
}
map[lo - first] = ptr;
} else {
self.walk_indirect_window(ptr, level - 1, lo, first, map)?;
}
}
Ok(())
}
fn scan_block_map(
&mut self,
inode: &Inode,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
for i in 0..DIRECT_BLOCKS {
let ptr = u64::from(get_u32(&inode.block, i * 4));
if ptr != 0 {
self.check_block(ptr)?;
}
}
for level in 1..=INDIRECT_LEVELS {
let slot = DIRECT_BLOCKS + level as usize - 1;
let root = u64::from(get_u32(&inode.block, slot * 4));
self.scan_indirect(root, level, visited)?;
}
Ok(())
}
fn scan_indirect(
&mut self,
block: u64,
level: u32,
visited: &mut HashSet<u64>,
) -> Result<(), ReadError> {
if block == 0 {
return Ok(());
}
if !visited.insert(block) {
return Ok(());
}
let buf = self.block(block)?;
let per_block = self.block_size / 4;
for i in 0..per_block {
let ptr = u64::from(get_u32(&buf, i * 4));
if level == 1 {
if ptr != 0 {
self.check_block(ptr)?;
}
} else {
self.scan_indirect(ptr, level - 1, visited)?;
}
}
Ok(())
}
pub fn read_data(&mut self, inode: &Inode) -> Result<Vec<u8>, ReadError> {
let want = self.whole_file_len(inode)?;
let len = usize::try_from(want).map_err(|_| ReadError::FileTooLarge {
size: want,
limit: usize::MAX as u64,
})?;
let mut data = vec![0u8; len];
let filled = self.read_into(inode, 0, &mut data)?;
data.truncate(filled);
Ok(data)
}
pub fn read_data_to(&mut self, inode: &Inode, mut out: impl Write) -> Result<u64, ReadError> {
refuse_ciphertext(inode)?;
let want = self.whole_file_len(inode)?;
if is_inline(inode) {
let content = self.inline_content(inode)?;
out.write_all(&content)?;
return Ok(content.len() as u64);
}
let bs = self.block_size as u64;
let zeros = vec![0u8; self.block_size];
let mut written = 0u64;
while written < want {
let first = usize::try_from(written / bs).unwrap_or(usize::MAX);
let remaining_blocks = (want - written).div_ceil(bs);
let count = usize::try_from(remaining_blocks.min(MAP_WINDOW_BLOCKS as u64))
.unwrap_or(MAP_WINDOW_BLOCKS);
let map = self.map_window(inode, first, count)?;
for run in runs(&map, self.max_run_blocks()) {
if let Some(bytes) = self.read_run(&run)? {
let take = usize::try_from((want - written).min(bytes.len() as u64))
.unwrap_or(bytes.len());
out.write_all(&bytes[..take])?;
written += take as u64;
} else {
for &phys in &map[run.at..run.at + run.len] {
let left = want - written;
let take = usize::try_from(left.min(bs)).unwrap_or(self.block_size);
if phys == 0 {
out.write_all(&zeros[..take])?;
} else {
let block = self.block(phys)?;
out.write_all(&block[..take])?;
}
written += take as u64;
if written >= want {
break;
}
}
}
if written >= want {
break;
}
}
}
Ok(written)
}
pub fn read_into(
&mut self,
inode: &Inode,
offset: u64,
buf: &mut [u8],
) -> Result<usize, ReadError> {
refuse_ciphertext(inode)?;
if is_inline(inode) {
let content = self.inline_content(inode)?;
let from = usize::try_from(offset)
.unwrap_or(usize::MAX)
.min(content.len());
let take = (content.len() - from).min(buf.len());
buf[..take].copy_from_slice(&content[from..from + take]);
return Ok(take);
}
let size = self.file_len(inode);
if offset >= size || buf.is_empty() {
return Ok(0);
}
let bs = self.block_size as u64;
let want = (size - offset).min(buf.len() as u64);
let first = usize::try_from(offset / bs).unwrap_or(usize::MAX);
let last = usize::try_from((offset + want - 1) / bs).unwrap_or(usize::MAX);
let count = last - first + 1;
let mut skip = usize::try_from(offset % bs).unwrap_or(0);
let mut filled = 0usize;
let want_len = usize::try_from(want).unwrap_or(usize::MAX);
let map = self.map_window(inode, first, count)?;
for run in runs(&map, self.max_run_blocks()) {
if let Some(bytes) = self.read_run(&run)? {
let take = (bytes.len() - skip).min(want_len - filled);
buf[filled..filled + take].copy_from_slice(&bytes[skip..skip + take]);
filled += take;
skip = 0;
} else {
for &phys in &map[run.at..run.at + run.len] {
let take = (self.block_size - skip).min(want_len - filled);
if phys == 0 {
buf[filled..filled + take].fill(0);
} else {
let block = self.block(phys)?;
buf[filled..filled + take].copy_from_slice(&block[skip..skip + take]);
}
filled += take;
skip = 0;
if filled >= want_len {
break;
}
}
}
if filled >= want_len {
break;
}
}
Ok(filled)
}
fn whole_file_len(&mut self, inode: &Inode) -> Result<u64, ReadError> {
let size = self.file_len(inode);
if size > self.limits.max_file_bytes {
return Err(ReadError::FileTooLarge {
size,
limit: self.limits.max_file_bytes,
});
}
Ok(size)
}
pub(crate) fn file_len(&mut self, inode: &Inode) -> u64 {
if is_inline(inode) {
return self.inline_content(inode).map_or(0, |c| c.len() as u64);
}
if !maps_data(inode) {
return 0;
}
let mapped =
(self.logical_block_count(inode) as u64).saturating_mul(self.block_size as u64);
inode.size.min(mapped)
}
fn max_names(&mut self) -> usize {
usize::try_from(self.source_len() / MIN_DIRENT_LEN).unwrap_or(usize::MAX)
}
#[must_use]
pub fn journal_replay(&self) -> Option<&JournalReplay> {
match self.journal.as_deref().map(|j| &j.outcome) {
Some(Outcome::Replayed(report, _)) => Some(report),
None | Some(Outcome::NotReplayed(_)) => None,
}
}
#[must_use]
pub fn needs_recovery(&self) -> bool {
self.needs_recovery
}
#[must_use]
pub fn state_on_disk(&self) -> u16 {
self.state_on_disk
}
fn left_state(&self) -> Vec<ReadError> {
let mut out = Vec::new();
if self.needs_recovery || self.state_on_disk & STATE_CLEAN == 0 {
out.push(ReadError::NotCleanlyUnmounted);
}
if self.state_on_disk & STATE_ERRORS != 0 {
out.push(ReadError::ErrorsDetected);
}
out
}
pub fn read_block(&mut self, block: u64) -> Result<Vec<u8>, ReadError> {
self.block(block)
}
pub fn journal_superblock(
&mut self,
) -> Result<Option<crate::journal::JournalSuperblock>, ReadError> {
let Some(first) = self.journal_superblock_block()? else {
return Ok(None);
};
let block = self.block(first)?;
Ok(Some(crate::journal::JournalSuperblock::read_from(&block)?))
}
pub(crate) fn journal_superblock_block(&mut self) -> Result<Option<u64>, ReadError> {
if !self.feature.has_journal() || self.sb.journal_inum == 0 {
return Ok(None);
}
let inode = self.inode(self.sb.journal_inum)?;
let want = self.logical_block_count(&inode).min(1);
let first = self
.map_window(&inode, 0, want)?
.first()
.copied()
.filter(|&b| b != 0)
.ok_or(ReadError::BadJournal)?;
Ok(Some(first))
}
pub fn read_symlink(&mut self, inode: &Inode) -> Result<Vec<u8>, ReadError> {
refuse_ciphertext(inode)?;
if is_inline(inode) {
let target = self.inline_content(inode)?;
if target.len() > MAX_PATH {
return Err(ReadError::FileTooLarge {
size: target.len() as u64,
limit: MAX_PATH as u64,
});
}
return Ok(target);
}
if target_in_block_area(inode) {
let len = usize::try_from(inode.size)
.unwrap_or(usize::MAX)
.min(inode.block.len());
return Ok(inode.block[..len].to_vec());
}
if inode.size > MAX_PATH as u64 {
return Err(ReadError::FileTooLarge {
size: inode.size,
limit: MAX_PATH as u64,
});
}
self.read_data(inode)
}
pub fn xattrs(&mut self, inode: &Inode) -> Result<Vec<Xattr>, ReadError> {
let stored = self.stored_xattrs(inode)?;
let mut out = Vec::new();
let mut values_read: HashMap<u32, Vec<u8>> = HashMap::new();
for entry in stored {
if entry.is_the_formats() {
continue;
}
let value = match entry.value {
XattrValue::Here(value) => value,
XattrValue::InInode { inode, size } => {
if let Some(value) = values_read.get(&inode) {
if value.len() != size as usize {
return Err(ReadError::BadValueInode {
inode,
fault: "it holds another length than the attribute declares",
});
}
value.clone()
} else {
let value = self.value_in_inode(inode, size)?;
values_read.insert(inode, value.clone());
value
}
}
};
out.push(Xattr {
name: entry.name,
value,
});
}
for x in &mut out {
if x.name != Acl::ACCESS_NAME && x.name != Acl::DEFAULT_NAME {
continue;
}
let acl =
crate::ondisk::decode_acl(&x.value).map_err(|source| ReadError::MalformedAcl {
name: x.name.clone(),
source,
})?;
x.value = acl.encode();
}
Ok(out)
}
fn stored_xattrs(&mut self, inode: &Inode) -> Result<Vec<StoredXattr>, ReadError> {
let mut stored = parse_inline_stored(&inode.inline_xattr)?;
if inode.file_acl != 0 {
let block = self.block(inode.file_acl)?;
stored.extend(parse_block_stored(&block)?);
}
Ok(stored)
}
fn value_inode(&mut self, number: u32, size: u32) -> Result<Inode, ReadError> {
let bad = |fault| ReadError::BadValueInode {
inode: number,
fault,
};
if self.feature.incompat.bits() & INCOMPAT_EA_INODE == 0 {
return Err(bad(
"the filesystem does not have ea_inode, which keeps a value in an inode",
));
}
if size > MAX_XATTR_VALUE {
return Err(bad(
"the attribute declares a value longer than the 65536 bytes one may hold",
));
}
let held = match self.inode(number) {
Ok(held) => held,
Err(e @ ReadError::Io { .. }) => return Err(e),
Err(_) => return Err(bad("it is not an inode the filesystem has")),
};
if !held.flags.contains(InodeFlags::EA_INODE) {
return Err(bad(
"it does not carry the flag of an inode holding a value",
));
}
if held.size != u64::from(size) {
return Err(bad("it holds another length than the attribute declares"));
}
Ok(held)
}
fn value_in_inode(&mut self, number: u32, size: u32) -> Result<Vec<u8>, ReadError> {
let held = self.value_inode(number, size)?;
match self.read_data(&held) {
Ok(value) => Ok(value),
Err(e @ ReadError::Io { .. }) => Err(e),
Err(_) => Err(ReadError::BadValueInode {
inode: number,
fault: "its data does not read",
}),
}
}
fn inline_content(&self, inode: &Inode) -> Result<Vec<u8>, ReadError> {
let mut content = inode.block.to_vec();
content.extend(inline_extension(inode)?);
let size = usize::try_from(inode.size).unwrap_or(usize::MAX);
if size > content.len() {
return Err(ReadError::BadInlineData {
fault: "its size is past what its block area and system.data hold",
});
}
content.truncate(size);
Ok(content)
}
#[must_use]
pub fn device(&self, inode: &Inode) -> (u32, u32) {
let b0 = u32::from_le_bytes([
inode.block[0],
inode.block[1],
inode.block[2],
inode.block[3],
]);
let b1 = u32::from_le_bytes([
inode.block[4],
inode.block[5],
inode.block[6],
inode.block[7],
]);
decode_device(b0, b1)
}
pub fn read_dir(&mut self, inode: &Inode) -> Result<Vec<Entry>, ReadError> {
let cap = self.limits.max_walk_entries.min(self.max_names());
let mut entries = Vec::new();
self.for_each_dir_entry(inode, |entry| {
if entries.len() >= cap {
return Err(ReadError::WalkTooLarge { limit: cap });
}
entries.push(entry);
Ok(std::ops::ControlFlow::Continue(()))
})?;
Ok(entries)
}
fn for_each_dir_entry<F>(&mut self, inode: &Inode, mut visit: F) -> Result<(), ReadError>
where
F: FnMut(Entry) -> Result<std::ops::ControlFlow<()>, ReadError>,
{
refuse_ciphertext(inode)?;
let mut on_fault = Self::read_record_fault(self.policy);
if is_inline(inode) {
for region in inline_dir_regions(inode)? {
if self
.for_each_entry_in_block(
®ion,
Names::Plain,
None,
&mut on_fault,
&mut visit,
)?
.is_break()
{
return Ok(());
}
}
return Ok(());
}
let mut seen_blocks = HashSet::new();
for phys in self.data_blocks(inode)? {
if phys == 0 || !seen_blocks.insert(phys) {
continue;
}
let block = self.block(phys)?;
if self
.for_each_entry_in_block(&block, Names::Plain, None, &mut on_fault, &mut visit)?
.is_break()
{
return Ok(());
}
}
Ok(())
}
fn for_each_entry_in_block<F>(
&self,
block: &[u8],
names: Names,
uninit_groups: Option<&HashSet<u32>>,
on_fault: &mut dyn FnMut(RecordFault, ReadError) -> Result<(), ReadError>,
visit: &mut F,
) -> Result<std::ops::ControlFlow<()>, ReadError>
where
F: FnMut(Entry) -> Result<std::ops::ControlFlow<()>, ReadError>,
{
let mut off = 0;
while off < block.len() {
let (entry, rec_len) = match DirEntry::read_from(&block[off..], block.len()) {
Ok(parsed) => parsed,
Err(e) => {
on_fault(RecordFault::Framing, ReadError::Parse(e))?;
break;
}
};
if rec_len == 0 {
on_fault(RecordFault::Framing, ReadError::BadDirectory)?;
break;
}
if entry.inode != 0 {
let fault = if names == Names::Plain && is_hostile_entry(&entry.name) {
Some((
RecordFault::Name,
ReadError::HostileName { inode: entry.inode },
))
} else if let Err(e) = self.check_dir_entry_inode(entry.inode) {
Some((RecordFault::Reference, e))
} else if uninit_groups.is_some_and(|groups| {
groups.contains(&((entry.inode - 1) / self.sb.inodes_per_group.max(1)))
}) {
Some((
RecordFault::Reference,
ReadError::InodeInUninitGroup { inode: entry.inode },
))
} else {
None
};
if let Some((kind, e)) = fault {
on_fault(kind, e)?;
off += rec_len;
continue;
}
let keep = visit(Entry {
name: entry.name,
inode: entry.inode,
file_type: entry.file_type,
})?;
if keep.is_break() {
return Ok(keep);
}
}
off += rec_len;
}
Ok(std::ops::ControlFlow::Continue(()))
}
fn read_record_fault(
policy: ReadPolicy,
) -> impl FnMut(RecordFault, ReadError) -> Result<(), ReadError> {
let fatal = policy.is_fatal(Severity::Structural);
move |kind, e| match kind {
RecordFault::Framing => Err(e),
RecordFault::Name | RecordFault::Reference if fatal => Err(e),
RecordFault::Name | RecordFault::Reference => Ok(()),
}
}
fn dir_index(&mut self, dir: &Inode) -> Result<Option<DirIndex>, ReadError> {
use crate::hash::{HashSignedness, HashVersion};
if !dir.flags.contains(InodeFlags::INDEX) || !self.feature.has_dir_index() {
return Ok(None);
}
let blocks = self.data_blocks(dir)?;
let Some(root) = self.dir_block_at(&blocks, 0)? else {
return Ok(None);
};
let Ok((code, levels)) = read_dx_root_info(&root) else {
return Ok(None);
};
let (version, signedness) = match code {
0..=2 => (code, HashSignedness::from_flags(self.sb.flags)),
3..=5 => (code - 3, HashSignedness::Unsigned),
_ => return Ok(None),
};
let Some(version) = HashVersion::from_u8(version) else {
return Ok(None);
};
let deepest = if self.feature.incompat.bits() & INCOMPAT_LARGEDIR != 0 {
DX_MAX_INDIRECT_LEVELS + 1
} else {
DX_MAX_INDIRECT_LEVELS
};
if levels > deepest {
return Ok(None);
}
Ok(Some(DirIndex {
blocks,
root,
levels,
version,
signedness,
}))
}
fn descend(
&mut self,
index: &DirIndex,
major: Option<u32>,
) -> Result<Option<IndexPath>, ReadError> {
let mut path: IndexPath = Vec::with_capacity(usize::from(index.levels) + 1);
let mut block = index.root.clone();
let mut count_offset = DX_ROOT_COUNT_OFFSET;
for level in 0..=index.levels {
let Ok(entries) = read_dx_entries(&block, count_offset) else {
return Ok(None);
};
let at = major.map_or(0, |major| {
entries[1..].partition_point(|entry| entry.hash <= major)
});
let child = entries[at].block;
path.push((entries, at));
if level < index.levels {
let Some(node) = self.dir_block_at(&index.blocks, child)? else {
return Ok(None);
};
block = node;
count_offset = DX_NODE_COUNT_OFFSET;
}
}
Ok(Some(path))
}
fn find_indexed(&mut self, dir: &Inode, name: &[u8]) -> Result<Indexed, ReadError> {
use crate::hash::{dir_hash, unmoved_major};
refuse_ciphertext(dir)?;
if dir.flags.contains(InodeFlags::CASEFOLD) {
return Ok(Indexed::Unusable);
}
let Some(index) = self.dir_index(dir)? else {
return Ok(Indexed::Unusable);
};
let hash = dir_hash(name, index.version, index.signedness, &self.sb.hash_seed);
let unmoved = unmoved_major(hash.major);
let Some(mut path) = self.descend(&index, Some(hash.major))? else {
return Ok(Indexed::Unusable);
};
for _ in 0..index.blocks.len() {
let (entries, at) = path.last().expect("the descent pushed one level at least");
let Some(leaf) = self.dir_block_at(&index.blocks, entries[*at].block)? else {
return Ok(Indexed::Unusable);
};
let mut found = 0;
let mut on_fault = Self::read_record_fault(self.policy);
let hit = self.for_each_entry_in_block(
&leaf,
Names::Plain,
None,
&mut on_fault,
&mut |entry: Entry| {
Ok(if entry.name == name {
found = entry.inode;
std::ops::ControlFlow::Break(())
} else {
std::ops::ControlFlow::Continue(())
})
},
)?;
if hit.is_break() {
return Ok(Indexed::Found(found));
}
let next = match self.next_leaf(&index.blocks, &mut path)? {
Step::Leaf(next) => next,
Step::End => return Ok(Indexed::Absent),
Step::Unusable => return Ok(Indexed::Unusable),
};
let continues = next == hash.major | DX_HASH_CONTINUED
|| unmoved.is_some_and(|unmoved| next & !DX_HASH_CONTINUED == unmoved);
if !continues {
return Ok(Indexed::Absent);
}
}
Ok(Indexed::Unusable)
}
fn scan_index(
&mut self,
ino: u32,
dir: &Inode,
judged: &mut HashSet<JudgedLeaf>,
out: &mut Findings<Anomaly>,
) {
use crate::hash::{dir_hash, unmoved_major};
if dir.flags.contains(InodeFlags::CASEFOLD) {
return;
}
let Ok(Some(index)) = self.dir_index(dir) else {
return;
};
let Ok(Some(mut path)) = self.descend(&index, None) else {
return;
};
let mut leaves: Vec<(u32, u32)> = Vec::new();
let mut low = 0u32;
for _ in 0..index.blocks.len() {
let (entries, at) = path.last().expect("the descent pushed one level at least");
leaves.push((entries[*at].block, low));
match self.next_leaf(&index.blocks, &mut path) {
Ok(Step::Leaf(next)) => low = next,
Ok(Step::End) => break,
Ok(Step::Unusable) | Err(_) => return,
}
}
let fits = |major: u32, low: u32, high: Option<u32>| {
low & !DX_HASH_CONTINUED <= major
&& high.is_none_or(|high| {
major < high & !DX_HASH_CONTINUED || major | DX_HASH_CONTINUED == high
})
};
let names = Names::of(dir);
for (k, &(leaf, low)) in leaves.iter().enumerate() {
let high = leaves.get(k + 1).map(|&(_, next)| next);
let Some(&phys) = index.blocks.get(leaf as usize) else {
continue;
};
if !judged.insert((phys, low, high, index.version, index.signedness, names)) {
continue;
}
let Ok(Some(block)) = self.dir_block_at(&index.blocks, leaf) else {
continue;
};
let mut misplaced = None;
let mut on_fault = Self::read_record_fault(self.policy);
let walked = self.for_each_entry_in_block(
&block,
names,
None,
&mut on_fault,
&mut |entry: Entry| {
let major = dir_hash(
&entry.name,
index.version,
index.signedness,
&self.sb.hash_seed,
)
.major;
let placed = fits(major, low, high)
|| unmoved_major(major).is_some_and(|unmoved| fits(unmoved, low, high));
Ok(if placed {
std::ops::ControlFlow::Continue(())
} else {
misplaced = Some(entry.inode);
std::ops::ControlFlow::Break(())
})
},
);
if walked.is_ok()
&& let Some(inode) = misplaced
{
out.push(anomaly_at_inode(
&ReadError::IndexMisplacesName { inode },
ino,
));
return;
}
}
}
fn next_leaf(&mut self, blocks: &[u64], path: &mut IndexPath) -> Result<Step, ReadError> {
let Some(level) = path
.iter()
.rposition(|(entries, at)| at + 1 < entries.len())
else {
return Ok(Step::End);
};
path[level].1 += 1;
let hash = path[level].0[path[level].1].hash;
for below in level + 1..path.len() {
let (entries, at) = &path[below - 1];
let Some(node) = self.dir_block_at(blocks, entries[*at].block)? else {
return Ok(Step::Unusable);
};
let Ok(entries) = read_dx_entries(&node, DX_NODE_COUNT_OFFSET) else {
return Ok(Step::Unusable);
};
path[below] = (entries, 0);
}
Ok(Step::Leaf(hash))
}
fn dir_block_at(&mut self, blocks: &[u64], logical: u32) -> Result<Option<Vec<u8>>, ReadError> {
match blocks
.get(logical as usize)
.copied()
.filter(|&phys| phys != 0)
{
Some(phys) => Ok(Some(self.block(phys)?)),
None => Ok(None),
}
}
pub fn lookup(&mut self, path: &[u8]) -> Result<(u32, Inode), ReadError> {
self.resolve(path, true)
}
pub fn lookup_no_follow(&mut self, path: &[u8]) -> Result<(u32, Inode), ReadError> {
self.resolve(path, false)
}
fn resolve(&mut self, path: &[u8], follow_final: bool) -> Result<(u32, Inode), ReadError> {
crate::resolve::drive(self, path, follow_final)
}
pub fn walk(&mut self) -> Result<Vec<WalkEntry>, ReadError> {
let mut out = Vec::new();
self.walk_with::<ReadError>(|_, entry| {
out.push(entry);
Ok(())
})?;
Ok(out)
}
pub fn walk_with<E: From<ReadError>>(
&mut self,
mut visit: impl FnMut(&mut Self, WalkEntry) -> Result<(), E>,
) -> Result<(), E> {
crate::walk::drive(self, |reader, entry| visit(reader, entry))
}
}
impl<R: Read + Seek> crate::resolve::Resolve for Reader<R> {
type Ancestor = u32;
type Node = (u32, Inode);
type Error = ReadError;
fn root_node(&mut self) -> Result<Self::Node, ReadError> {
Ok((ROOT_INO, self.inode(ROOT_INO)?))
}
fn ancestor_of(&self, node: &Self::Node) -> u32 {
node.0
}
fn node_at(&mut self, ancestor: u32) -> Result<Self::Node, ReadError> {
Ok((ancestor, self.inode(ancestor)?))
}
fn is_directory(&self, node: &Self::Node) -> bool {
is_dir(&node.1)
}
fn find_name(
&mut self,
dir: &Self::Node,
name: &[u8],
) -> Result<Option<Self::Node>, ReadError> {
match self.find_indexed(&dir.1, name)? {
Indexed::Found(ino) => return Ok(Some((ino, self.inode(ino)?))),
Indexed::Absent => return Ok(None),
Indexed::Unusable => {}
}
let mut found = None;
self.for_each_dir_entry(&dir.1, |e| {
Ok(if e.name == name {
found = Some(e.inode);
std::ops::ControlFlow::Break(())
} else {
std::ops::ControlFlow::Continue(())
})
})?;
match found {
Some(ino) => Ok(Some((ino, self.inode(ino)?))),
None => Ok(None),
}
}
fn read_link(&mut self, node: &Self::Node, path: &[u8]) -> Result<Option<Vec<u8>>, ReadError> {
if !is_symlink(&node.1) {
return Ok(None);
}
if node.1.size > MAX_PATH as u64 {
return Err(self.not_found(path));
}
Ok(Some(self.read_symlink(&node.1)?))
}
fn not_found(&self, path: &[u8]) -> ReadError {
ReadError::NotFound {
path: path.to_vec(),
}
}
fn not_a_directory(&self, _node: &Self::Node, path: &[u8]) -> ReadError {
ReadError::NotADirectory {
path: path.to_vec(),
}
}
fn too_many_links(&self, path: &[u8]) -> ReadError {
ReadError::SymlinkLoop {
path: path.to_vec(),
}
}
}
impl<R: Read + Seek> crate::walk::Walk for Reader<R> {
type Pending = (Vec<u8>, u32);
type Entry = WalkEntry;
type Key = u32;
type Error = ReadError;
fn cap(&mut self) -> usize {
self.limits.max_walk_entries.min(self.max_names())
}
fn seed(&mut self) -> Result<crate::walk::Seed<Self>, ReadError> {
let root = self.inode(ROOT_INO)?;
if !is_dir(&root) {
return Err(ReadError::NotADirectory {
path: b"/".to_vec(),
});
}
let children = self.walk_children(&root, &[])?;
Ok((children, vec![ROOT_INO]))
}
fn resolve(&mut self, (path, number): Self::Pending) -> Result<WalkEntry, ReadError> {
let inode = self.inode(number)?;
Ok(WalkEntry {
path,
number,
inode,
})
}
fn descend_key(&self, entry: &WalkEntry) -> Option<u32> {
is_dir(&entry.inode).then_some(entry.number)
}
fn children(&mut self, entry: &WalkEntry) -> Result<Vec<Self::Pending>, ReadError> {
self.walk_children(&entry.inode, &entry.path)
}
fn repeated(&mut self, entry: &WalkEntry) -> Result<(), ReadError> {
let err = ReadError::RepeatedDirectory {
inode: entry.number,
};
if self.policy.is_fatal(err.anomaly().severity) {
return Err(err);
}
Ok(())
}
fn too_large(limit: usize) -> ReadError {
ReadError::WalkTooLarge { limit }
}
}
impl<R: Read + Seek> Reader<R> {
fn walk_children(
&mut self,
inode: &Inode,
prefix: &[u8],
) -> Result<Vec<(Vec<u8>, u32)>, ReadError> {
let mut entries = self.read_dir(inode)?;
entries.sort_by(|a, b| a.name.cmp(&b.name));
let mut children = Vec::new();
for e in entries.iter().rev() {
if crate::path::is_dot_entry(&e.name) {
continue;
}
let path = crate::walk::child_path(prefix, &e.name)
.ok_or(ReadError::PathTooLong { limit: MAX_PATH })?;
children.push((path, e.inode));
}
Ok(children)
}
}
impl From<ReadError> for TreeError {
fn from(err: ReadError) -> Self {
match err {
ReadError::Io { kind, message } => TreeError::Io { kind, message },
ReadError::UnsupportedIncompat { .. }
| ReadError::UnsupportedLayout { .. }
| ReadError::Encrypted { .. } => TreeError::Unsupported {
family: Family::Ext,
detail: err.to_string(),
},
ReadError::FileTooLarge { .. } => TreeError::limit(Family::Ext, Bound::FileBytes, &err),
ReadError::PathTooLong { .. } => TreeError::limit(Family::Ext, Bound::PathBytes, &err),
ReadError::WalkTooLarge { .. } => TreeError::limit(Family::Ext, Bound::Entries, &err),
other => TreeError::Malformed {
family: Family::Ext,
detail: other.to_string(),
},
}
}
}
struct JournalLog<'a, R> {
reader: &'a mut Reader<R>,
inode: Inode,
window: Option<(u32, Vec<u64>)>,
}
impl<R: Read + Seek> crate::replay::Log for JournalLog<'_, R> {
fn locate(&mut self, n: u32) -> Result<u64, ReadError> {
let width = MAP_WINDOW_BLOCKS as u32;
let start = n - n % width;
if self.window.as_ref().map(|(first, _)| *first) != Some(start) {
let map = self
.reader
.map_window(&self.inode, start as usize, MAP_WINDOW_BLOCKS)?;
self.window = Some((start, map));
}
let at = self
.window
.as_ref()
.and_then(|(_, map)| map.get((n - start) as usize).copied())
.unwrap_or(0);
if at == 0 {
return Err(ReadError::JournalMalformed {
log_block: n,
detail: "a log block the journal file does not map",
});
}
Ok(at)
}
fn read(&mut self, n: u32) -> Result<Vec<u8>, ReadError> {
let at = self.locate(n)?;
self.reader.block(at)
}
}
impl<R: Read + Seek> FsTree for Reader<R> {
type Node = Inode;
fn family(&self) -> Family {
Family::Ext
}
fn max_file_bytes(&self) -> u64 {
self.limits.max_file_bytes
}
fn walk_tree<E, F>(&mut self, mut visit: F) -> Result<(), E>
where
E: From<TreeError>,
F: FnMut(&mut Self, TreeEntry<Inode>) -> Result<(), E>,
{
let root = self
.inode(ROOT_INO)
.map_err(|e| E::from(TreeError::from(e)))?;
let root_entry = WalkEntry {
path: Vec::new(),
number: ROOT_INO,
inode: root,
};
let root_entry = tree_entry(self, root_entry).map_err(E::from)?;
visit(self, root_entry)?;
let outcome = self.walk_with::<WalkFail<E>>(|reader, entry| {
let node = tree_entry(reader, entry).map_err(WalkFail::Tree)?;
visit(reader, node).map_err(WalkFail::Visitor)
});
match outcome {
Ok(()) => Ok(()),
Err(WalkFail::Read(e)) => Err(E::from(TreeError::from(e))),
Err(WalkFail::Tree(e)) => Err(E::from(e)),
Err(WalkFail::Visitor(e)) => Err(e),
}
}
fn stat(&mut self, node: &Inode, _synthesis: &Synthesis) -> Result<Attributes, TreeError> {
let xattrs = self.xattrs(node)?;
Ok(Attributes::read(self.metadata(node), xattrs))
}
fn read_bytes(
&mut self,
node: &Inode,
offset: u64,
buf: &mut [u8],
) -> Result<usize, TreeError> {
if node.mode & 0o170000 != 0o100000 {
return Ok(0);
}
Ok(Reader::read_into(self, node, offset, buf)?)
}
fn link_target(&mut self, node: &Inode) -> Result<Vec<u8>, TreeError> {
if node.mode & 0o170000 != 0o120000 {
return Err(TreeError::Malformed {
family: Family::Ext,
detail: "the node is not a symbolic link".to_string(),
});
}
Ok(self.read_symlink(node)?)
}
fn find(&mut self, path: &[u8]) -> Result<Child<Inode>, TreeError> {
let (number, inode) = self.lookup(path).map_err(|e| not_found_or(path, e))?;
let kind = node_kind(self, number, &inode)?;
Ok(Child::new(crate::tree::last_name(path), kind, inode))
}
fn list(&mut self, dir: &Inode) -> Result<Vec<Child<Inode>>, TreeError> {
if !is_dir(dir) {
return Err(crate::tree::not_a_directory(Family::Ext));
}
let entries = self.read_dir(dir)?.into_iter().map(|e| (e.name, e.inode));
let mut out = Vec::new();
for (name, number) in crate::tree::listed(Family::Ext, entries)? {
let inode = self.inode(number)?;
let kind = node_kind(self, number, &inode)?;
out.push(Child::new(name, kind, inode));
}
Ok(out)
}
fn usage(&mut self) -> Result<Usage, TreeError> {
let mut free = 0u64;
for group in 0..self.group_count() {
free += u64::from(self.group_descriptor(group)?.free_blocks_count);
}
let shift = if self.feature.ro_compat.bits() & RO_COMPAT_BIGALLOC != 0 {
self.sb
.log_cluster_size
.saturating_sub(self.sb.log_block_size)
.min(30)
} else {
0
};
Ok(Usage::new(
(self.block_size as u64) << shift,
self.sb.blocks_count.div_ceil(1 << shift),
free,
))
}
}
type WalkFail<E> = crate::tree::WalkFail<ReadError, E>;
impl<E> From<ReadError> for WalkFail<E> {
fn from(err: ReadError) -> Self {
WalkFail::Read(err)
}
}
fn tree_entry<R: Read + Seek>(
reader: &mut Reader<R>,
entry: WalkEntry,
) -> Result<TreeEntry<Inode>, TreeError> {
let WalkEntry {
path,
number,
inode,
..
} = entry;
let kind = node_kind(reader, number, &inode)?;
let shared = (!matches!(kind, NodeKind::Directory) && inode.links_count > 1)
.then_some(u64::from(number));
let mut entry = TreeEntry::new(path, kind, inode);
entry.shared = shared;
Ok(entry)
}
fn node_kind<R: Read + Seek>(
reader: &mut Reader<R>,
number: u32,
inode: &Inode,
) -> Result<NodeKind, TreeError> {
Ok(match inode.mode & 0o170000 {
0o040000 => NodeKind::Directory,
0o100000 => NodeKind::File {
size: reader.file_len(inode),
},
0o120000 => NodeKind::Symlink,
0o020000 => {
let (major, minor) = reader.device(inode);
NodeKind::CharDevice { major, minor }
}
0o060000 => {
let (major, minor) = reader.device(inode);
NodeKind::BlockDevice { major, minor }
}
0o010000 => NodeKind::Fifo,
0o140000 => NodeKind::Socket,
other => {
return Err(TreeError::Malformed {
family: Family::Ext,
detail: format!(
"inode {number} records file type {other:#o}, which names no file type"
),
});
}
})
}
fn not_found_or(path: &[u8], err: ReadError) -> TreeError {
match err {
ReadError::NotFound { .. }
| ReadError::NotADirectory { .. }
| ReadError::SymlinkLoop { .. } => TreeError::NotFound {
family: Family::Ext,
path: path.to_vec(),
},
other => TreeError::from(other),
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::geometry::GrowReservation;
use crate::materialize::{FormatOptions, format};
use crate::source::{Metadata, TreeBuilder};
use crate::time::Timestamp;
const MIB: u64 = 1024 * 1024;
fn opts() -> FormatOptions {
let mut o = FormatOptions::new([1u8; 16], Timestamp::from_secs(1_700_000_000), [0u8; 16]);
o.grow = GrowReservation::UpTo(32 * 1024 * MIB);
o
}
#[test]
fn an_io_failure_keeps_the_kind_it_was_classified_as() {
let truncated = ReadError::from(std::io::Error::new(
std::io::ErrorKind::UnexpectedEof,
"image ends mid-superblock",
));
let ReadError::Io { kind, message } = &truncated else {
panic!("expected an i/o error, got {truncated:?}");
};
assert_eq!(*kind, std::io::ErrorKind::UnexpectedEof);
assert!(message.contains("image ends mid-superblock"), "{message}");
assert!(
truncated.to_string().contains("image ends mid-superblock"),
"{truncated}"
);
let denied = ReadError::from(std::io::Error::from(std::io::ErrorKind::PermissionDenied));
assert!(matches!(
denied,
ReadError::Io {
kind: std::io::ErrorKind::PermissionDenied,
..
}
));
}
#[test]
fn a_size_past_the_logical_ceiling_is_not_a_length_a_read_yields() {
let time = Timestamp::from_secs(1_700_000_000);
let source = TreeBuilder::new().file(
b"/hello".to_vec(),
b"hi\n".to_vec(),
Metadata::new(0o644, time),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, mut inode) = r.lookup(b"/hello").unwrap();
assert_eq!(r.file_len(&inode), 3);
let ceiling = MAX_LOGICAL_BLOCKS * r.block_size as u64;
for claimed in [ceiling + 1, ceiling * 2, u64::MAX] {
inode.size = claimed;
assert_eq!(r.file_len(&inode), ceiling, "claimed {claimed}");
}
inode.size = ceiling;
assert_eq!(r.file_len(&inode), ceiling);
}
fn walk_tree<R: Read + Seek>(r: &mut Reader<R>) -> std::collections::BTreeMap<Vec<u8>, Inode> {
r.walk()
.unwrap()
.into_iter()
.map(|e| (e.path, e.inode))
.collect()
}
#[test]
fn reads_back_an_empty_filesystem() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert_eq!(r.superblock().inodes_count, 16384);
let root = r.inode(2).unwrap();
let entries = r.read_dir(&root).unwrap();
let names: Vec<_> = entries.iter().map(|e| e.name.clone()).collect();
assert!(names.contains(&b".".to_vec()));
assert!(names.contains(&b"..".to_vec()));
assert!(names.contains(&b"lost+found".to_vec()));
}
#[test]
fn default_image_carries_a_readable_empty_journal() {
let image = format(TreeBuilder::new(), 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(r.feature().has_journal());
assert_eq!(r.superblock().journal_inum, 8);
assert_eq!(r.superblock().jnl_backup_type, 1);
let jsb = r.journal_superblock().unwrap().expect("has a journal");
assert_eq!(jsb.block_size, 4096);
assert_eq!(jsb.max_len, 4096);
assert_eq!(jsb.first, 1);
assert_eq!(jsb.sequence, 1);
assert_eq!(jsb.start, 0);
assert_eq!(jsb.nr_users, 1);
assert_eq!(jsb.uuid, [1u8; 16]);
let inode = r.inode(8).unwrap();
assert_eq!(inode.mode, 0o100600);
assert_eq!(inode.links_count, 1);
assert!(inode.flags.contains(InodeFlags::EXTENTS));
assert_eq!(inode.size, 4096 * 4096);
for (i, word) in inode.block.as_chunks::<4>().0.iter().enumerate() {
let w = u32::from_le_bytes(*word);
assert_eq!(r.superblock().jnl_blocks[i], w, "jnl_blocks[{i}]");
}
assert_eq!(r.superblock().jnl_blocks[16], inode.size as u32);
}
#[test]
fn no_journal_feature_leaves_inode_eight_empty() {
let mut o = opts();
o.feature.compat = crate::feature::Compat::from_bits(
o.feature.compat.bits()
& !(crate::feature::Compat::HAS_JOURNAL.bits()
| crate::feature::Compat::ORPHAN_FILE.bits()),
);
let image = format(TreeBuilder::new(), 64 * MIB, o).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(!r.feature().has_journal());
assert_eq!(r.superblock().journal_inum, 0);
assert_eq!(r.superblock().jnl_backup_type, 0);
assert!(r.journal_superblock().unwrap().is_none());
let inode = r.inode(8).unwrap();
assert_eq!(inode.mode, 0);
assert_eq!(inode.links_count, 0);
assert_eq!(inode.size, 0);
assert_eq!(inode.blocks, 0);
}
#[test]
fn round_trips_a_populated_tree() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.symlink(
b"/etc/mtab".to_vec(),
b"/proc/self/mounts".to_vec(),
m(0o777),
)
.file(
b"/big".to_vec(),
vec![0x42; 20_000],
m(0o600).owned_by(7, 9),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let hostname = &tree[&b"/etc/hostname".to_vec()];
assert_eq!(r.read_data(hostname).unwrap(), b"ferrosys\n");
assert_eq!(hostname.mode, 0o100644);
let big = &tree[&b"/big".to_vec()];
assert_eq!(r.read_data(big).unwrap(), vec![0x42; 20_000]);
assert_eq!(big.uid, 7);
assert_eq!(big.gid, 9);
let mtab = &tree[&b"/etc/mtab".to_vec()];
assert_eq!(r.read_symlink(mtab).unwrap(), b"/proc/self/mounts");
assert_eq!(mtab.mode & 0o170000, 0o120000);
}
#[test]
fn round_trips_hardlinks_as_a_shared_inode() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.file(b"/a".to_vec(), b"shared".to_vec(), m(0o644))
.hardlink(b"/b".to_vec(), b"/a".to_vec(), m(0o644));
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let entries = r.read_dir(&root).unwrap();
let a = entries.iter().find(|e| e.name == b"a").unwrap().inode;
let b = entries.iter().find(|e| e.name == b"b").unwrap().inode;
assert_eq!(a, b, "hard links share one inode");
assert_eq!(r.inode(a).unwrap().links_count, 2);
}
#[test]
fn round_trips_a_slow_symlink() {
let time = Timestamp::from_secs(1_700_000_000);
let target = vec![b'p'; 200];
let src = TreeBuilder::new().symlink(
b"/link".to_vec(),
target.clone(),
Metadata::new(0o777, time),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let link_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"link")
.unwrap()
.inode;
let link = r.inode(link_ino).unwrap();
assert_eq!(r.read_symlink(&link).unwrap(), target);
}
fn inode_offset(bytes: &[u8], number: u32) -> usize {
let mut r = Reader::open(std::io::Cursor::new(bytes)).unwrap();
let inode_size = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
table * 4096 + (number as usize - 1) * inode_size
}
#[test]
fn a_short_target_is_the_block_area_however_many_blocks_the_link_is_charged_for() {
let time = Timestamp::from_secs(1_700_000_000);
let long = vec![b't'; 60];
let src = TreeBuilder::new()
.symlink(
b"/short".to_vec(),
b"/etc/passwd".to_vec(),
Metadata::new(0o777, time),
)
.symlink(b"/long".to_vec(), long.clone(), Metadata::new(0o777, time));
let pristine = format(src, 16 * MIB, opts_no_csum()).unwrap().into_bytes();
let number = {
let mut r = Reader::open(std::io::Cursor::new(&pristine)).unwrap();
r.lookup_no_follow(b"/short").expect("the link is there").0
};
for charged in [0u32, 8, 24, 128] {
let mut bytes = pristine.clone();
let at = inode_offset(&bytes, number);
crate::ondisk::put_u32(&mut bytes[at..], 0x1C, charged);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, inode) = r.lookup_no_follow(b"/short").expect("the link");
assert_eq!(inode.blocks, u64::from(charged));
assert_eq!(
r.read_symlink(&inode).expect("read the target"),
b"/etc/passwd",
"charged for {charged} sectors"
);
}
let mut r = Reader::open(std::io::Cursor::new(&pristine)).unwrap();
let (_, inode) = r.lookup_no_follow(b"/long").expect("the link");
assert!(inode.blocks > 0, "a sixty-byte target owns a block");
assert_eq!(r.read_symlink(&inode).expect("read the target"), long);
}
#[test]
fn the_bytes_above_i_blocks_are_read_as_a_high_half_only_where_the_feature_says_so() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().symlink(
b"/short".to_vec(),
b"/etc/passwd".to_vec(),
Metadata::new(0o777, time),
);
let mut options = opts_no_csum();
options.feature = FeatureSet::EXT2;
let mut bytes = format(src, 16 * MIB, options).unwrap().into_bytes();
let (number, target) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (number, inode) = r.lookup_no_follow(b"/short").expect("the link is there");
(number, r.read_symlink(&inode).expect("read the target"))
};
assert_eq!(target, b"/etc/passwd", "the fixture is a fast symlink");
let at = inode_offset(&bytes, number);
crate::ondisk::put_u16(&mut bytes[at..], 0x74, 0xBEEF);
crate::ondisk::put_u16(&mut bytes[at..], 0x76, 0xFACE);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, inode) = r
.lookup_no_follow(b"/short")
.expect("the link is still there");
assert_eq!(
inode.blocks, 0,
"without huge_file the block count is i_blocks_lo alone"
);
assert_eq!(
inode.file_acl, 0,
"without 64bit the attribute block is i_file_acl alone"
);
assert_eq!(
r.read_symlink(&inode).expect("read the target"),
b"/etc/passwd",
"the link still reads as the fast symlink it is"
);
}
#[test]
fn a_directory_entry_with_no_name_is_flagged_and_never_walked() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.file(b"/g".to_vec(), b"y".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 16 * MIB, opts_no_csum()).unwrap().into_bytes();
let block = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(ROOT_INO).unwrap();
usize::try_from(r.extent_leaves(&root).unwrap()[0].start).unwrap() * 4096
};
let mut off = block;
loop {
let (entry, rec_len) = DirEntry::read_from(&bytes[off..block + 4096], 4096).unwrap();
if entry.name == b"f" {
break;
}
off += rec_len;
}
bytes[off + 6] = 0;
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(matches!(r.walk(), Err(ReadError::HostileName { .. })));
let mut lenient = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let walked = lenient
.walk()
.expect("a lenient walk hands back what it can");
for entry in &walked {
assert!(
!entry.path.is_empty() && !entry.path.ends_with(b"/"),
"the walk built {:?} from a nameless entry",
String::from_utf8_lossy(&entry.path)
);
}
assert!(
walked.iter().any(|e| e.path == b"/g"),
"the entry beside it survives: {:?}",
walked.iter().map(|e| &e.path).collect::<Vec<_>>()
);
let report = r.scan();
assert!(
report.anomalies().iter().any(|a| {
a.location.inode == Some(ROOT_INO)
&& a.category == Category::Directory
&& a.severity == Severity::Structural
}),
"the scan reports the nameless entry: {:#?}",
report.anomalies()
);
assert!(!report.is_clean());
}
#[test]
fn a_root_that_is_not_a_directory_is_refused_before_it_is_descended_into() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 16 * MIB, opts_no_csum()).unwrap().into_bytes();
let at = inode_offset(&bytes, ROOT_INO);
crate::ondisk::put_u16(&mut bytes[at..], 0, 0o100_755);
crate::ondisk::put_u32(&mut bytes[at..], 4, 0xFFFF_FFFF);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(
matches!(r.walk(), Err(ReadError::NotADirectory { ref path }) if path == b"/"),
"a root that is not a directory is refused by name"
);
let walked: Result<(), ReadError> = r.walk_with(|_, _| Ok(()));
assert!(matches!(walked, Err(ReadError::NotADirectory { .. })));
}
#[test]
fn a_symlink_owning_a_data_block_reads_its_target_from_the_block() {
let time = Timestamp::from_secs(1_700_000_000);
let target = vec![b'p'; 200];
let src = TreeBuilder::new().symlink(
b"/link".to_vec(),
target.clone(),
Metadata::new(0o777, time),
);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let ino = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.lookup_no_follow(b"/link").expect("lookup /link").0
};
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(&mut bytes[off..], 0x04, 40);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let link = r.inode(ino).unwrap();
assert!(link.blocks > 0, "the symlink owns a data block");
assert_eq!(
r.read_symlink(&link).unwrap(),
target[..40].to_vec(),
"the target came from the block the inode owns, not from its block area"
);
}
#[test]
fn a_fast_symlink_carrying_an_attribute_block_still_reads_inline() {
let time = Timestamp::from_secs(1_700_000_000);
let target = b"/proc/self/mounts".to_vec();
let src = TreeBuilder::new()
.symlink(
b"/mtab".to_vec(),
target.clone(),
Metadata::new(0o777, time),
)
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, link) = r.lookup_no_follow(b"/mtab").expect("lookup /mtab");
assert_ne!(link.file_acl, 0, "the attribute set spilled to a block");
assert_ne!(link.blocks, 0, "which is charged to i_blocks");
assert_eq!(r.read_symlink(&link).unwrap(), target);
}
#[test]
fn a_link_sized_past_its_block_area_is_refused_rather_than_read_as_text() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().symlink(
b"/mtab".to_vec(),
b"/proc/self/mounts".to_vec(),
Metadata::new(0o777, time),
);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let ino = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.lookup_no_follow(b"/mtab").expect("lookup /mtab").0
};
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(&mut bytes[off..], 0x04, 100);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let link = r.inode(ino).unwrap();
assert!(
matches!(
r.read_symlink(&link),
Err(ReadError::OutOfRange { what: "block", .. })
),
"the area's text is no block map"
);
}
#[test]
fn a_stored_acl_that_is_not_an_acl_is_refused_and_reported() {
let time = Timestamp::from_secs(1_700_000_000);
let acl = crate::acl::Acl::new(vec![
crate::acl::AclEntry {
who: crate::acl::AclQualifier::UserObj,
perm: crate::acl::Acl::READ | crate::acl::Acl::WRITE,
},
crate::acl::AclEntry {
who: crate::acl::AclQualifier::GroupObj,
perm: crate::acl::Acl::READ,
},
crate::acl::AclEntry {
who: crate::acl::AclQualifier::Other,
perm: crate::acl::Acl::READ,
},
])
.expect("a well-formed ACL");
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(crate::acl::Acl::ACCESS_NAME.to_vec(), acl.encode());
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let stored = crate::ondisk::encode_acl(&acl);
let at = bytes
.windows(stored.len())
.position(|w| w == stored.as_slice())
.expect("the stored ACL is in the image");
bytes[at] = 0x07;
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (ino, _) = r.lookup(b"/f").expect("lookup /f");
let inode = r.inode(ino).expect("the inode still reads");
assert!(
matches!(r.xattrs(&inode), Err(ReadError::MalformedAcl { .. })),
"a value that is not an ACL has no form to be read back in"
);
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Xattr && a.location.inode == Some(ino))
.expect("the scan names the inode holding it");
assert_eq!(found.severity, Severity::Structural);
}
#[test]
fn an_attribute_block_pointer_past_the_filesystem_is_refused() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, blocks_count) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
(
r.lookup(b"/f").expect("lookup /f").0,
r.superblock().blocks_count,
)
};
let planted = crate::xattr::Xattr {
name: b"user.neighbour".to_vec(),
value: b"from the next partition".to_vec(),
};
let neighbour = crate::ondisk::encode_block(std::slice::from_ref(&planted), 4096);
assert_eq!(
crate::ondisk::parse_block(&neighbour).unwrap(),
vec![planted],
"the planted block is a readable attribute block"
);
let at = usize::try_from(blocks_count).unwrap() * 4096;
bytes.resize(at + 4096, 0);
bytes[at..at + 4096].copy_from_slice(&neighbour);
let off = inode_offset(&bytes, ino);
crate::ondisk::put_u32(
&mut bytes[off..],
0x68,
u32::try_from(blocks_count).unwrap(),
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert_eq!(inode.file_acl, blocks_count);
assert!(
matches!(
r.xattrs(&inode),
Err(ReadError::OutOfRange { what: "block", index }) if index == blocks_count
),
"an attribute block outside the filesystem was read: {:?}",
r.xattrs(&inode)
);
}
fn plant_beyond(bytes: &mut Vec<u8>, block: &[u8]) -> u64 {
let at = bytes.len();
assert_eq!(at % 4096, 0, "the image ends on a block boundary");
bytes.extend_from_slice(block);
(at / 4096) as u64
}
#[test]
fn a_superblock_whose_geometry_would_scan_nothing_is_refused_at_open() {
let image = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
let total = SuperBlock::read_from(&image[1024..2048])
.expect("the superblock")
.inodes_count;
for (field, offset, value) in [
("s_inodes_count", 0x00usize, 0u32),
("s_inodes_count", 0x00, total - 1),
("s_inodes_count", 0x00, total + 1),
("s_blocks_count", 0x04, 0),
("s_first_data_block", 0x14, 0xffff_ffff),
] {
let mut mangled = image.clone();
crate::ondisk::put_u32(&mut mangled[1024..], offset, value);
let refused = Reader::open_with(
std::io::Cursor::new(&mangled),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.map(|_| ());
assert!(
matches!(
&refused,
Err(ReadError::Parse(ParseError::InvalidField { field: f, value: v, .. }))
if *f == field && *v == u64::from(value)
),
"{field} = {value}: {refused:?}"
);
}
let mut rootless = image.clone();
crate::ondisk::put_u32(&mut rootless[1024..], 0x28, 1);
crate::ondisk::put_u32(&mut rootless[1024..], 0x00, 1);
let refused = Reader::open_with(
std::io::Cursor::new(&rootless),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.map(|_| ());
assert!(
matches!(
&refused,
Err(ReadError::Parse(ParseError::InvalidField {
field: "s_inodes_count",
value: 1,
..
}))
),
"a geometry with no root inode: {refused:?}"
);
let mut small = opts_no_csum();
small.feature = small.feature.with_block_size(1024);
let image = format(TreeBuilder::new(), 16 * MIB, small)
.unwrap()
.into_bytes();
let mut mangled = image.clone();
crate::ondisk::put_u32(&mut mangled[1024..], 0x04, 1);
let refused = Reader::open_with(
std::io::Cursor::new(&mangled),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.map(|_| ());
assert!(
matches!(
&refused,
Err(ReadError::Parse(ParseError::InvalidField {
field: "s_blocks_count",
value: 1,
..
}))
),
"one block at a one-kibibyte block size scans nothing: {refused:?}"
);
}
#[test]
fn an_inode_table_pointed_past_the_filesystem_is_refused() {
let mut bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
let (table, blocks_count, inode_size) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
(
usize::try_from(r.group_descriptor(0).unwrap().inode_table).unwrap(),
r.superblock().blocks_count,
usize::from(r.superblock().inode_size),
)
};
assert_eq!(bytes.len() as u64, blocks_count * 4096);
let mut planted = bytes[table * 4096..table * 4096 + 4096].to_vec();
put_u16(&mut planted, inode_size, 0o120777);
let neighbour = plant_beyond(&mut bytes, &planted);
assert_eq!(neighbour, blocks_count);
crate::ondisk::put_u32(&mut bytes[4096..], 0x08, u32::try_from(neighbour).unwrap());
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(
matches!(
r.inode(2),
Err(ReadError::OutOfRange {
what: "inode",
index: 2
})
),
"the root inode was read from past the filesystem: {:?}",
r.inode(2)
);
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| { a.category == Category::Inode && a.severity == Severity::Structural }),
"the scan reports the unreachable inode table: {report:?}"
);
}
#[test]
fn an_inode_at_the_end_of_a_table_that_runs_past_the_filesystem_is_refused() {
let mut bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
let (blocks_count, inode_size, ipg) = {
let r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
(
r.superblock().blocks_count,
u64::from(r.superblock().inode_size),
u64::from(r.superblock().inodes_per_group),
)
};
let table = blocks_count - 1;
crate::ondisk::put_u32(&mut bytes[4096..], 0x08, u32::try_from(table).unwrap());
plant_beyond(&mut bytes, &vec![0u8; 4096]);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let per_block = 4096 / inode_size;
assert!(r.inode(u32::try_from(per_block).unwrap()).is_ok());
let outside = u32::try_from(per_block + 1).unwrap();
assert!(outside <= u32::try_from(ipg).unwrap());
assert!(
matches!(
r.inode(outside),
Err(ReadError::OutOfRange { what: "inode", .. })
),
"an inode past the filesystem's final block was read: {:?}",
r.inode(outside)
);
}
#[test]
fn an_inode_bitmap_pointed_past_the_filesystem_is_refused() {
let mut bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
let blocks_count = Reader::open(std::io::Cursor::new(&bytes))
.unwrap()
.superblock()
.blocks_count;
let neighbour = plant_beyond(&mut bytes, &vec![0xffu8; 4096]);
crate::ondisk::put_u32(&mut bytes[4096..], 0x04, u32::try_from(neighbour).unwrap());
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Bitmap && a.location.group == Some(0))
.unwrap_or_else(|| panic!("the scan reports the unreachable bitmap: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert_eq!(
found.location.block,
Some(blocks_count),
"the anomaly names the block the descriptor pointed at"
);
}
#[test]
fn an_extent_index_pointed_past_the_filesystem_is_refused() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (ino, blocks_count) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
(
r.lookup(b"/f").expect("lookup /f").0,
r.superblock().blocks_count,
)
};
let mut planted = vec![0u8; 4096];
crate::extent::write_node(
&ExtentNode::Leaves(vec![crate::ondisk::ExtentLeaf {
block: 0,
len: 1,
start: 100,
initialized: true,
}]),
crate::extent::node_capacity(4096),
&mut planted,
)
.expect("the planted node is well formed");
assert!(parse_node(&planted).is_ok());
let neighbour = plant_beyond(&mut bytes, &planted);
let off = inode_offset(&bytes, ino) + 0x28;
put_u16(&mut bytes[off..], 6, 1);
let entry = crate::ondisk::ExtentIdx {
block: 0,
leaf: neighbour,
}
.to_bytes();
bytes[off + EXTENT_ENTRY_SIZE..off + 2 * EXTENT_ENTRY_SIZE].copy_from_slice(&entry);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert!(
matches!(
r.read_data(&inode),
Err(ReadError::OutOfRange { what: "block", index }) if index == blocks_count
),
"an extent node outside the filesystem was followed: {:?}",
r.read_data(&inode)
);
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::ExtentTree && a.location.inode == Some(ino))
.unwrap_or_else(|| panic!("the scan reports the unreachable node: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
}
fn with_extent_tree(
entries: impl Fn(u64) -> Vec<crate::ondisk::ExtentIdx>,
nodes: impl Fn(u64, u64) -> Vec<(u64, ExtentNode)>,
size: u64,
) -> (Vec<u8>, u32) {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), vec![b'A'; 4096], Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (ino, data, free) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
let (ino, inode) = r.lookup(b"/f").expect("lookup /f");
let data = r.extent_leaves(&inode).unwrap()[0].start;
(ino, data, r.superblock().blocks_count - 100)
};
for (at, node) in nodes(free, data) {
let at = usize::try_from(at).unwrap() * 4096;
crate::extent::write_node(
&node,
crate::extent::node_capacity(4096),
&mut bytes[at..at + 4096],
)
.expect("a well-formed node");
}
let at = inode_offset(&bytes, ino);
let mut root = [0u8; 60];
let depth = nodes(free, data)
.iter()
.map(|(_, n)| n.depth())
.max()
.unwrap_or(0)
+ 1;
crate::extent::write_node(
&ExtentNode::Index {
depth,
entries: entries(free),
},
4,
&mut root,
)
.expect("a well-formed root");
bytes[at + 0x28..at + 0x28 + 60].copy_from_slice(&root);
crate::bytes::put_u32(&mut bytes, at + 0x04, size as u32);
crate::bytes::put_u32(&mut bytes, at + 0x6C, (size >> 32) as u32);
(bytes, ino)
}
#[test]
fn a_leaf_outside_its_index_range_is_refused_by_a_read_and_reported_by_a_scan() {
use crate::ondisk::{ExtentIdx, ExtentLeaf};
let leaf = |block: u32, start: u64| {
ExtentNode::Leaves(vec![ExtentLeaf {
block,
len: 1,
start,
initialized: true,
}])
};
let (bytes, ino) = with_extent_tree(
|free| {
vec![
ExtentIdx {
block: 0,
leaf: free,
},
ExtentIdx {
block: 100,
leaf: free + 1,
},
]
},
|free, data| vec![(free, leaf(5000, data)), (free + 1, leaf(100, data))],
5001 * 4096,
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert_eq!(r.read_data(&inode), Err(ReadError::BadExtentTree));
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.location.inode == Some(ino)
&& a.detail == ReadError::BadExtentTree.to_string()),
"{:?}",
report.anomalies()
);
}
#[test]
fn a_cyclic_extent_tree_is_reported_by_a_scan() {
use crate::ondisk::ExtentIdx;
let (bytes, ino) = with_extent_tree(
|free| {
vec![ExtentIdx {
block: 0,
leaf: free,
}]
},
|free, _| {
vec![(
free,
ExtentNode::Index {
depth: 1,
entries: vec![ExtentIdx {
block: 0,
leaf: free,
}],
},
)]
},
4096,
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert_eq!(r.read_data(&inode), Err(ReadError::BadExtentTree));
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.location.inode == Some(ino)
&& a.detail == ReadError::BadExtentTree.to_string()),
"{:?}",
report.anomalies()
);
}
#[test]
fn an_extent_header_whose_counts_disagree_is_reported() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let clean = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let ino = {
let mut r = Reader::open(std::io::Cursor::new(&clean)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
r.lookup(b"/f").expect("lookup /f").0
};
let root = inode_offset(&clean, ino) + 0x28;
for (field, at, value) in [
("eh_max", 4u16, 0u16),
("eh_max", 4, 5), ("eh_entries", 2, 2), ] {
let mut bytes = clean.clone();
if field == "eh_entries" {
put_u16(&mut bytes[root..], 4, 1);
}
put_u16(&mut bytes[root..], usize::from(at), value);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let inode = r.inode(ino).unwrap();
assert!(
matches!(
r.read_data(&inode),
Err(ReadError::Parse(ParseError::InvalidField {
structure: "ExtentHeader",
field: f,
..
})) if f == field
),
"a {field} of {value} was followed as a mapping: {:?}",
r.read_data(&inode)
);
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::ExtentTree && a.location.inode == Some(ino))
.unwrap_or_else(|| panic!("a {field} of {value} is reported: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(!report.is_clean());
}
}
#[test]
fn a_directory_entry_naming_an_inode_that_does_not_exist_is_refused() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (block, inodes_count) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
let root = r.inode(ROOT_INO).unwrap();
let block = r.extent_leaves(&root).unwrap()[0].start;
(
usize::try_from(block).unwrap() * 4096,
r.superblock().inodes_count,
)
};
let mut off = block;
loop {
let (entry, rec_len) = DirEntry::read_from(&bytes[off..block + 4096], 4096).unwrap();
if entry.name == b"f" {
break;
}
off += rec_len;
}
let missing = inodes_count + 1;
crate::ondisk::put_u32(&mut bytes[off..], 0, missing);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(ROOT_INO).unwrap();
assert_eq!(
r.read_dir(&root).err(),
Some(ReadError::DirEntryNoSuchInode { inode: missing }),
"a directory listing handed back an entry naming inode {missing}"
);
assert!(r.walk().is_err());
let mut lenient = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let root = lenient.inode(ROOT_INO).unwrap();
let names: Vec<Vec<u8>> = lenient
.read_dir(&root)
.expect("a lenient read hands back what it can")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.iter().any(|n| n == b"."),
"the good entries survive: {names:?}"
);
assert!(
!names.iter().any(|n| n == b"f"),
"and the one naming nothing does not: {names:?}"
);
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Directory && a.location.inode == Some(ROOT_INO))
.unwrap_or_else(|| panic!("the scan reports the bad reference: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(
found.detail.contains(&missing.to_string()),
"the finding names the inode the entry pointed at: {found:?}"
);
}
#[test]
fn a_directory_record_that_does_not_frame_is_a_finding_and_not_only_a_refused_listing() {
let mut ext2 = opts();
ext2.feature = FeatureSet::EXT2;
let mut bytes = format(TreeBuilder::new(), 16 * MIB, ext2)
.unwrap()
.into_bytes();
let block = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
let root = r.inode(ROOT_INO).unwrap();
r.data_blocks(&root).unwrap()[0]
};
let at = usize::try_from(block).unwrap() * 4096 + 4;
bytes[at..at + 2].copy_from_slice(&0u16.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(ROOT_INO).unwrap();
assert!(matches!(
r.read_dir(&root),
Err(ReadError::Parse(ParseError::InvalidField {
structure: "DirEntry",
field: "rec_len",
value: 0,
}))
));
let report = r.scan();
assert!(!report.is_clean(), "the scan is not clean");
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Directory && a.location.inode == Some(ROOT_INO))
.unwrap_or_else(|| panic!("the scan names the root directory: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(found.detail.contains("rec_len"), "{found:?}");
}
#[test]
fn a_directory_entry_carrying_a_name_no_directory_can_hold_is_refused() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let block = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(r.scan().is_clean(), "the image is clean before the edit");
let root = r.inode(ROOT_INO).unwrap();
usize::try_from(r.extent_leaves(&root).unwrap()[0].start).unwrap() * 4096
};
let mut off = block;
loop {
let (entry, rec_len) = DirEntry::read_from(&bytes[off..block + 4096], 4096).unwrap();
if entry.name == b"f" {
break;
}
off += rec_len;
}
let (entry, _) = DirEntry::read_from(&bytes[off..block + 4096], 4096).unwrap();
let named = entry.inode;
bytes[off + 8] = b'/';
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(ROOT_INO).unwrap();
assert_eq!(
r.read_dir(&root).err(),
Some(ReadError::HostileName { inode: named }),
"a directory listing handed back a name no directory can hold"
);
assert!(r.walk().is_err());
let mut lenient = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let root = lenient.inode(ROOT_INO).unwrap();
let names: Vec<Vec<u8>> = lenient
.read_dir(&root)
.expect("a lenient read hands back what it can")
.into_iter()
.map(|e| e.name)
.collect();
assert!(
names.iter().any(|n| n == b"."),
"the good entries survive: {names:?}"
);
assert!(
!names.iter().any(|n| n.contains(&b'/')),
"and the one no directory can hold does not: {names:?}"
);
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Directory && a.location.inode == Some(ROOT_INO))
.unwrap_or_else(|| panic!("the scan reports the name: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(!report.is_clean());
assert!(
!found.detail.contains('/'),
"the finding does not render the name: {found:?}"
);
}
#[test]
fn the_descriptor_stride_ignores_s_desc_size_without_64bit() {
let mut o = opts();
o.feature.incompat = o.feature.incompat.without(Incompat::SIXTY_FOUR_BIT);
o.grow = GrowReservation::None;
let bytes = format(TreeBuilder::new(), 256 * MIB, o)
.unwrap()
.into_bytes();
let pristine = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_32);
assert!(
r.group_count() > 1,
"the image must span more than one group for the stride to show"
);
(0..r.group_count())
.map(|g| r.group_descriptor(g).unwrap())
.collect::<Vec<_>>()
};
let mut corrupt = bytes.clone();
put_u16(&mut corrupt[1024..], 0xfe, GroupDescriptor::SIZE_64 as u16);
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_32);
let after: Vec<_> = (0..r.group_count())
.map(|g| r.group_descriptor(g).unwrap())
.collect();
assert_eq!(
after, pristine,
"a meaningless s_desc_size moved the descriptors"
);
let wide = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let r = Reader::open(std::io::Cursor::new(wide.as_bytes())).unwrap();
assert!(r.feature().is_64bit());
assert_eq!(r.desc_size(), GroupDescriptor::SIZE_64);
}
#[test]
fn a_64bit_superblock_rejects_an_out_of_bounds_desc_size() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
for bad in [32u16, 8192] {
let mut corrupt = image.as_bytes().to_vec();
put_u16(&mut corrupt[1024..], 0xfe, bad);
assert!(
matches!(
Reader::open(std::io::Cursor::new(&corrupt)),
Err(ReadError::Parse(ParseError::InvalidField {
field: "s_desc_size",
..
}))
),
"a 64bit image with s_desc_size={bad} must be refused at open"
);
}
assert!(Reader::open(std::io::Cursor::new(image.as_bytes())).is_ok());
}
#[test]
fn a_corrupted_index_tail_reserved_word_is_caught() {
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..64u32 {
let mut name = format!("/d/entry-{i:04}").into_bytes();
name.resize(b"/d/".len() + 200, b'x');
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, o).unwrap().into_bytes();
let (root_block, tail) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").expect("the directory is present");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"the directory must be hash-indexed for it to have an index tail"
);
r.verify_checksums()
.expect("it verifies clean to begin with");
let block = r.data_blocks(&dir).unwrap()[0];
let raw = r.block(block).unwrap();
let limit = usize::from(get_u16(&raw, DX_ROOT_COUNT_OFFSET));
(block, dx_tail_offset(DX_ROOT_COUNT_OFFSET, limit))
};
let at = usize::try_from(root_block).unwrap() * 1024 + tail;
assert_eq!(bytes[at..at + 4], [0; 4], "the writer leaves it zero");
bytes[at] = 0xff;
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(
matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "directory block",
..
})
),
"a flipped dt_reserved went unnoticed: {:?}",
r.verify_checksums()
);
}
#[test]
fn unsupported_features_are_reported_by_name() {
let d =
describe_unsupported_incompat(0x0000_0100 | 0x0000_4000 | 0x0000_8000 | 0x8000_0000);
for name in ["mmp", "large_dir", "inline_data", "0x80000000"] {
assert!(d.contains(name), "{name} is missing from {d:?}");
}
let order: Vec<usize> = ["mmp", "large_dir", "inline_data", "0x80000000"]
.iter()
.map(|n| d.find(n).unwrap())
.collect();
assert!(
order.windows(2).all(|w| w[0] < w[1]),
"features are listed in ascending bit order: {d:?}"
);
}
#[test]
fn every_incompat_bit_is_named_by_exactly_one_table() {
for (name, bit) in UNMODELLED_INCOMPAT {
assert_eq!(bit.count_ones(), 1, "{name} names exactly one bit");
assert!(
Incompat::from_bits(*bit).names().is_empty(),
"{name} ({bit:#x}) is named by the feature word too"
);
if [
INCOMPAT_RECOVER,
INCOMPAT_ENCRYPT,
INCOMPAT_EA_INODE,
INCOMPAT_LARGEDIR,
INCOMPAT_INLINE_DATA,
INCOMPAT_CASEFOLD,
INCOMPAT_MMP,
]
.contains(bit)
{
assert_ne!(bit & SUPPORTED_INCOMPAT, 0, "{name} is followed");
continue;
}
assert_eq!(
bit & SUPPORTED_INCOMPAT,
0,
"{name} ({bit:#x}) is a feature the reader claims to follow"
);
}
}
#[test]
fn round_trips_inline_and_block_xattrs() {
let time = Timestamp::from_secs(1_700_000_000);
let cap = vec![
0x01, 0x00, 0x00, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
];
let src = TreeBuilder::new()
.directory(b"/bin".to_vec(), Metadata::new(0o755, time))
.file(
b"/bin/ping".to_vec(),
b"elf".to_vec(),
Metadata::new(0o755, time),
)
.xattr(b"security.capability".to_vec(), cap.clone())
.xattr(b"user.note".to_vec(), b"hi".to_vec())
.file(b"/big".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.blob".to_vec(), vec![0xAB; 300]);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let ping = &tree[&b"/bin/ping".to_vec()];
assert_eq!(ping.file_acl, 0, "small set stays inline, no acl block");
let mut got = r.xattrs(ping).unwrap();
got.sort_by(|a, b| a.name.cmp(&b.name));
assert_eq!(got.len(), 2);
assert_eq!(got[0].name, b"security.capability");
assert_eq!(got[0].value, cap);
assert_eq!(got[1].name, b"user.note");
let big = &tree[&b"/big".to_vec()];
assert_ne!(big.file_acl, 0, "large value spilled to a block");
let blob = r.xattrs(big).unwrap();
assert_eq!(blob.len(), 1);
assert_eq!(blob[0].name, b"user.blob");
assert_eq!(blob[0].value, vec![0xAB; 300]);
}
fn value_inode_image(held: &[u8], declared: u32, size: u64, feature: bool) -> Vec<u8> {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.note".to_vec(), b"hi".to_vec())
.file(b"/v".to_vec(), held.to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (f, v) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
(r.lookup(b"/f").unwrap().0, r.lookup(b"/v").unwrap().0)
};
if feature {
bytes[1024 + 0x60 + 1] |= 0x04;
}
let at = inode_offset(&bytes, f);
let region = at + 128 + usize::from(get_u16(&bytes, at + 0x80));
assert_eq!(get_u32(&bytes, region), 0xEA02_0000, "an in-inode region");
let entry = region + 4;
bytes[entry + 4..entry + 8].copy_from_slice(&v.to_le_bytes());
bytes[entry + 8..entry + 12].copy_from_slice(&declared.to_le_bytes());
let at = inode_offset(&bytes, v);
let flags = get_u32(&bytes, at + 0x20) | InodeFlags::EA_INODE.bits();
bytes[at + 0x20..at + 0x24].copy_from_slice(&flags.to_le_bytes());
bytes[at + 0x04..at + 0x08].copy_from_slice(&(size as u32).to_le_bytes());
bytes[at + 0x6C..at + 0x70].copy_from_slice(&((size >> 32) as u32).to_le_bytes());
bytes
}
fn value_inode_outcome(bytes: &[u8]) -> (Vec<String>, Result<Vec<Xattr>, ReadError>) {
let mut r = Reader::open_with(
std::io::Cursor::new(bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let (_, f) = r.lookup(b"/f").unwrap();
let found = r
.scan()
.anomalies()
.iter()
.map(|a| a.detail.clone())
.filter(|d| d.contains("keeps its value in"))
.collect();
(found, r.xattrs(&f))
}
#[test]
fn a_directorys_size_takes_its_high_word_under_large_dir_alone() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
let mut patched = bytes.clone();
let at = inode_offset(&patched, ROOT_INO) + 0x6c;
patched[at..at + 4].copy_from_slice(&1u32.to_le_bytes());
let size = |bytes: &[u8]| {
let mut r = Reader::open(std::io::Cursor::new(bytes)).unwrap();
r.inode(ROOT_INO).unwrap().size
};
let low = size(&bytes);
assert_eq!(
size(&patched),
low,
"without large_dir the word is not the size's"
);
patched[1024 + 0x60 + 1] |= 0x40;
assert_eq!(size(&patched), low | 1 << 32, "under large_dir it is");
}
#[test]
fn an_uninit_flag_without_its_feature_is_reported_and_not_honoured() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let f = Reader::open(std::io::Cursor::new(&bytes))
.unwrap()
.lookup(b"/f")
.unwrap()
.0;
let at = inode_offset(&bytes, f) + 0x20;
let flags = get_u32(&bytes, at) | InodeFlags::INDEX.bits();
bytes[at..at + 4].copy_from_slice(&flags.to_le_bytes());
bytes[4096 + 0x12] |= 1;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
let has = |want: &ReadError| {
report
.anomalies()
.iter()
.any(|a| a.detail == want.to_string())
};
assert!(
has(&ReadError::UninitFlagWithoutFeature { group: 0, flags: 1 }),
"{:?}",
report.anomalies()
);
assert!(
has(&ReadError::IndexFlagOnNonDirectory { inode: f }),
"the group's inodes are still examined: {:?}",
report.anomalies()
);
}
#[test]
fn a_value_kept_in_an_inode_reads_from_it_when_the_inode_holds_it() {
let held = b"the value".to_vec();
let bytes = value_inode_image(&held, 9, 9, true);
let (found, got) = value_inode_outcome(&bytes);
assert!(found.is_empty(), "{found:?}");
let got = got.expect("the attributes");
assert_eq!(got.len(), 1);
assert_eq!(
(got[0].name.as_slice(), got[0].value.clone()),
(&b"user.note"[..], held)
);
}
#[test]
fn a_value_inode_is_refused_without_the_feature_that_defines_one() {
let bytes = value_inode_image(b"the value", 9, 9, false);
let (found, got) = value_inode_outcome(&bytes);
assert_eq!(found.len(), 1, "{found:?}");
assert!(found[0].contains("does not have ea_inode"), "{found:?}");
assert!(
matches!(got, Err(ReadError::BadValueInode { .. })),
"{got:?}"
);
}
#[test]
fn a_value_declared_past_what_an_attribute_holds_is_refused_before_it_is_read() {
let bytes = value_inode_image(b"the value", 0xC000_0000, 0xC000_0000, true);
let (found, got) = value_inode_outcome(&bytes);
assert_eq!(found.len(), 1, "{found:?}");
assert!(
found[0].contains("longer than the 65536 bytes"),
"{found:?}"
);
assert!(
matches!(got, Err(ReadError::BadValueInode { .. })),
"{got:?}"
);
}
#[test]
fn a_value_inode_the_filesystem_lacks_is_reported_by_a_scan() {
let mut bytes = value_inode_image(b"the value", 9, 9, true);
let f = Reader::open(std::io::Cursor::new(&bytes))
.unwrap()
.lookup(b"/f")
.unwrap()
.0;
let at = inode_offset(&bytes, f);
let entry = at + 128 + usize::from(get_u16(&bytes, at + 0x80)) + 4;
bytes[entry + 4..entry + 8].copy_from_slice(&99_999u32.to_le_bytes());
let (found, got) = value_inode_outcome(&bytes);
assert_eq!(found.len(), 1, "{found:?}");
assert!(
found[0].contains("not an inode the filesystem has"),
"{found:?}"
);
assert!(
matches!(got, Err(ReadError::BadValueInode { inode: 99_999, .. })),
"{got:?}"
);
}
#[test]
fn a_xattr_set_splits_between_the_inode_and_its_block() {
let time = Timestamp::from_secs(1_700_000_000);
let huge = vec![0xAA; 4040];
let tiny = vec![0xBB; 60];
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.huge".to_vec(), huge.clone())
.xattr(b"user.tiny".to_vec(), tiny.clone());
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let f = &tree[&b"/f".to_vec()];
assert_ne!(f.file_acl, 0, "the huge value spilled to a block");
let inline = parse_inline(&f.inline_xattr).unwrap();
assert_eq!(inline.len(), 1, "the tiny value stayed inline");
assert_eq!(inline[0].name, b"user.tiny");
let mut got = r.xattrs(f).unwrap();
got.sort_by(|a, b| a.name.cmp(&b.name));
assert_eq!(got.len(), 2, "both regions read back as one set");
assert_eq!(got[0].name, b"user.huge");
assert_eq!(got[0].value, huge);
assert_eq!(got[1].name, b"user.tiny");
assert_eq!(got[1].value, tiny);
}
#[test]
fn round_trips_device_fifo_and_socket_nodes() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/dev".to_vec(), m(0o755))
.char_device(b"/dev/null".to_vec(), 1, 3, m(0o666))
.block_device(b"/dev/sda".to_vec(), 8, 0, m(0o660))
.fifo(b"/dev/initctl".to_vec(), m(0o600))
.socket(b"/dev/log".to_vec(), m(0o666));
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let tree = walk_tree(&mut r);
let null = &tree[&b"/dev/null".to_vec()];
assert_eq!(null.mode & 0o170000, 0o020000, "char device");
assert_eq!(null.mode & 0o7777, 0o666);
assert_eq!(r.device(null), (1, 3));
assert_eq!(null.blocks, 0, "no data blocks");
let sda = &tree[&b"/dev/sda".to_vec()];
assert_eq!(sda.mode & 0o170000, 0o060000, "block device");
assert_eq!(r.device(sda), (8, 0));
assert_eq!(
tree[&b"/dev/initctl".to_vec()].mode & 0o170000,
0o010000,
"fifo"
);
assert_eq!(
tree[&b"/dev/log".to_vec()].mode & 0o170000,
0o140000,
"socket"
);
}
#[test]
fn round_trips_distinct_and_fixed_timestamps() {
let m = Metadata::new(0o644, Timestamp::from_secs(500)).with_times(
Timestamp::from_secs(100),
Timestamp::from_secs(200),
Timestamp::from_secs(300),
);
let src = TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), m);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let f_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f = r.inode(f_ino).unwrap();
assert_eq!(f.atime, Timestamp::from_secs(100));
assert_eq!(f.ctime, Timestamp::from_secs(200));
assert_eq!(f.mtime, Timestamp::from_secs(300));
assert_eq!(
f.crtime,
Timestamp::from_secs(300),
"crtime derives from mtime"
);
let mut fixed = opts();
fixed.fixed_time = Some(Timestamp::from_secs(42));
let src = TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), m);
let image = format(src, 64 * MIB, fixed).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let root = r.inode(2).unwrap();
let f_ino = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f = r.inode(f_ino).unwrap();
assert_eq!(f.atime, Timestamp::from_secs(42));
assert_eq!(f.mtime, Timestamp::from_secs(42));
assert_eq!(f.crtime, Timestamp::from_secs(42));
}
#[test]
fn an_inode_without_the_creation_field_reads_as_no_birth_time() {
let born = Timestamp::from_secs(1_600_000_000);
let m = Metadata::new(0o644, Timestamp::from_secs(1_700_000_000));
let file = |meta| TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), meta);
let read = |inode_size: u16, meta| {
let mut o = opts();
o.feature.inode_size = inode_size;
let image = format(file(meta), 64 * MIB, o).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.into_bytes())).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
let stated = FsTree::stat(&mut r, &inode, &Synthesis::default())
.unwrap()
.meta;
assert_eq!(stated, r.metadata(&inode), "the one projection");
(r, inode, stated.btime)
};
assert_eq!(read(256, m.with_birth_time(born)).2, Some(born));
assert_eq!(read(256, m).2, Some(m.mtime));
let (_, _, none) = read(128, m);
assert_eq!(none, None);
let (r, mut inode, _) = read(256, m);
inode.extra_isize = 0;
assert_eq!(r.metadata(&inode).btime, None);
}
#[test]
fn the_fixed_time_clamp_reaches_the_reserved_structural_inodes() {
let format_time = Timestamp::from_secs(1_700_000_000);
let clamp = Timestamp::from_secs(42);
assert_ne!(
clamp, format_time,
"the clamp must differ from the format time"
);
let mut fixed = opts();
fixed.fixed_time = Some(clamp);
let image = format(TreeBuilder::new(), 64 * MIB, fixed).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
for ino in [7u32, 8, 12] {
let s = r.inode(ino).unwrap();
assert_eq!(
(s.atime, s.ctime, s.mtime, s.crtime),
(clamp, clamp, clamp, clamp),
"inode {ino}'s times honor the clamp, not the format time"
);
}
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
for ino in [7u32, 8, 12] {
assert_eq!(
r.inode(ino).unwrap().mtime,
format_time,
"inode {ino} takes the format time when the clamp is unset"
);
}
}
#[test]
fn verifies_metadata_checksums_and_detects_corruption() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 20_000], m(0o600));
let bytes = format(src, 512 * MIB, opts()).unwrap().into_bytes();
Reader::open(std::io::Cursor::new(&bytes))
.unwrap()
.verify_checksums()
.unwrap();
let mut corrupt = bytes.clone();
corrupt[1024 + 0x30] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "superblock",
..
})
));
let root_off = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.group_descriptor(0).unwrap().inode_table as usize * 4096 + 256
};
let mut corrupt = bytes.clone();
corrupt[root_off] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "inode",
index: 2,
..
})
));
let desc_size = {
let r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.superblock().desc_size as usize
};
assert_eq!(desc_size, 64, "the default feature set sets 64bit");
let mut corrupt = bytes.clone();
corrupt[4096 + desc_size + 0x0c] ^= 0xff; assert!(matches!(
Reader::open(std::io::Cursor::new(&corrupt))
.unwrap()
.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "group descriptor",
index: 1,
..
})
));
}
#[test]
fn verifies_bitmap_directory_and_xattr_checksums() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/etc/big".to_vec(), b"x".to_vec(), m(0o644))
.xattr(b"user.big".to_vec(), vec![0xcd; 400]);
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
{
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.verify_checksums()
.expect("a well-formed image verifies clean");
let report = r.scan();
assert!(
report.anomalies().is_empty(),
"a clean image scans clean, got {:?}",
report.anomalies()
);
}
let (bitmap_block, dir_block, xattr_block) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let bitmap_block = r.group_descriptor(0).unwrap().block_bitmap;
let root = r.inode(2).unwrap();
let dir_block = r.extent_leaves(&root).unwrap()[0].start;
let mut xattr_block = 0u64;
for e in r.walk().unwrap() {
if e.path == b"/etc/big" {
xattr_block = e.inode.file_acl;
}
}
assert_ne!(xattr_block, 0, "the file has an external attribute block");
(bitmap_block, dir_block, xattr_block)
};
let bs = 4096u64;
let corrupt_at = |block: u64, within: u64| {
let mut c = bytes.clone();
c[(block * bs + within) as usize] ^= 0xff;
c
};
let c = corrupt_at(bitmap_block, 0);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "block bitmap",
..
})
));
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.category == Category::Bitmap),
"scan reports a Bitmap anomaly"
);
let c = corrupt_at(dir_block, 40);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "directory block",
..
})
));
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.category == Category::Directory),
"scan reports a Directory anomaly"
);
let c = corrupt_at(xattr_block, 32);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "xattr block",
..
})
));
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.category == Category::Xattr),
"scan reports an Xattr anomaly"
);
}
fn two_level_directory() -> Vec<u8> {
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
let mut src = TreeBuilder::new().directory(b"/bigdir".to_vec(), Metadata::new(0o755, time));
for i in 0..800u32 {
src = src.file(big_entry(i), Vec::new(), Metadata::new(0o644, time));
}
format(src, 64 * MIB, o).unwrap().into_bytes()
}
fn big_entry(i: u32) -> Vec<u8> {
let mut name = format!("/bigdir/entry-{i:04}").into_bytes();
name.resize(b"/bigdir/".len() + 200, b'x');
name
}
#[test]
fn a_name_in_an_indexed_directory_is_found_through_its_index() {
let (source, reads) = Counting::new(two_level_directory());
let mut r = Reader::open(source).unwrap();
let (_, dir) = r.lookup(b"/bigdir").unwrap();
let listed = r.read_dir(&dir).unwrap();
assert_eq!(
listed.len(),
802,
"800 entries and the two every directory has"
);
for entry in listed.iter().filter(|e| e.name != b"." && e.name != b"..") {
assert_eq!(
r.find_indexed(&dir, &entry.name).unwrap(),
Indexed::Found(entry.inode),
"{}",
String::from_utf8_lossy(&entry.name)
);
}
let held = &big_entry(417)[b"/bigdir/".len()..];
let mut near = held.to_vec();
*near.last_mut().unwrap() = b'y';
for absent in [&b"entry-9999"[..], &near] {
assert_eq!(r.find_indexed(&dir, absent).unwrap(), Indexed::Absent);
}
reads.borrow_mut().clear();
assert!(matches!(
r.find_indexed(&dir, held).unwrap(),
Indexed::Found(_)
));
let read = reads.borrow().len();
assert!(
read <= 3,
"one lookup read {read} blocks: {:?}",
reads.borrow()
);
}
#[test]
fn a_run_of_names_sharing_a_hash_is_followed_across_the_leaves_it_spans() {
const RUN: [&str; 12] = [
"00000000", "000yur3r", "00ikgk6p", "038nnvs7", "04fj9czy", "06o4c9mm", "08fmpxko",
"0cfkev4t", "0dcul5zd", "0di2m3ht", "0e8lvhi2", "0fzu2fjy",
];
let seed = *b"ferrosys-htree\0\0";
let name = |suffix: &str| {
let mut name = b"run-".to_vec();
name.resize(192, b'x');
name.extend_from_slice(suffix.as_bytes());
name
};
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
o.hash_seed = seed;
o.hash_signedness = crate::hash::HashSignedness::Signed;
let mut src = TreeBuilder::new().directory(b"/run".to_vec(), Metadata::new(0o755, time));
for suffix in RUN {
let mut path = b"/run/".to_vec();
path.extend_from_slice(&name(suffix));
src = src.file(path, Vec::new(), Metadata::new(0o644, time));
}
let bytes = format(src, 64 * MIB, o).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/run").unwrap();
let index = r
.dir_index(&dir)
.unwrap()
.expect("an index this reader follows");
let root = read_dx_entries(&index.root, DX_ROOT_COUNT_OFFSET).unwrap();
let continued = root[1..]
.iter()
.filter(|e| e.hash & DX_HASH_CONTINUED != 0)
.count();
assert!(
continued >= 2,
"the run was not split across leaves: {root:?}"
);
let major = crate::hash::dir_hash(
&name(RUN[0]),
crate::hash::HashVersion::HalfMd4,
crate::hash::HashSignedness::Signed,
&seed,
)
.major;
assert_eq!(major, 0xe464_36ac, "the run's hash under this seed");
let listed = r.read_dir(&dir).unwrap();
for suffix in RUN {
let want = listed
.iter()
.find(|e| e.name == name(suffix))
.expect("listed")
.inode;
assert_eq!(
r.find_indexed(&dir, &name(suffix)).unwrap(),
Indexed::Found(want),
"{suffix}"
);
}
assert_eq!(
r.find_indexed(&dir, &name("zzzzzzzz")).unwrap(),
Indexed::Absent
);
assert!(r.scan().is_clean(), "{:?}", r.scan().anomalies());
}
#[test]
fn a_name_at_the_end_of_the_hash_space_is_found_under_either_reading_of_it() {
let seed = *b"ferrosys-htree\0\0";
let end_name = |suffix: &str| {
let mut name = b"eos-".to_vec();
name.resize(192, b'x');
name.extend_from_slice(suffix.as_bytes());
name
};
let ends = [end_name("001x3k0e"), end_name("0fyrqufv")];
let time = Timestamp::from_secs(1_700_000_000);
let mut o = opts_no_csum();
o.feature.block_size = 1024;
o.grow = GrowReservation::None;
o.hash_seed = seed;
o.hash_signedness = crate::hash::HashSignedness::Signed;
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..40u32 {
let mut path = format!("/d/fill-{i:04}").into_bytes();
path.resize(b"/d/".len() + 200, b'x');
src = src.file(path, Vec::new(), Metadata::new(0o644, time));
}
for name in &ends {
let mut path = b"/d/".to_vec();
path.extend_from_slice(name);
src = src.file(path, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, o).unwrap().into_bytes();
let root_at = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
let index = r
.dir_index(&dir)
.unwrap()
.expect("an index this reader follows");
let root = read_dx_entries(&index.root, DX_ROOT_COUNT_OFFSET).unwrap();
assert_eq!(
root.len(),
11,
"ten leaves of four and one of two: {root:?}"
);
assert_eq!(
root[10].hash, 0xFFFF_FFFC,
"the last leaf begins at the moved value"
);
index.blocks[0] as usize * 1024
};
let at = root_at + DX_ROOT_COUNT_OFFSET + DX_ENTRY_LEN * 10;
bytes[at..at + 4].copy_from_slice(&0xFFFF_FFFEu32.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
for name in &ends {
assert!(
matches!(r.find_indexed(&dir, name).unwrap(), Indexed::Found(_)),
"{}",
String::from_utf8_lossy(name)
);
}
assert!(r.scan().is_clean(), "{:?}", r.scan().anomalies());
}
#[test]
fn a_name_its_index_does_not_lead_to_is_reported_and_missed_through_the_index() {
let mut bytes = two_level_directory();
let (node_at, raised, leaf) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/bigdir").unwrap();
let index = r
.dir_index(&dir)
.unwrap()
.expect("an index this reader follows");
let root = read_dx_entries(&index.root, DX_ROOT_COUNT_OFFSET).unwrap();
let node_phys = index.blocks[root[0].block as usize];
let node = r.block(node_phys).unwrap();
let entries = read_dx_entries(&node, DX_NODE_COUNT_OFFSET).unwrap();
let leaf = r.block(index.blocks[entries[2].block as usize]).unwrap();
(node_phys as usize * 1024, entries[3].hash - 2, leaf)
};
let at = node_at + DX_NODE_COUNT_OFFSET + DX_ENTRY_LEN * 2;
bytes[at..at + 4].copy_from_slice(&raised.to_le_bytes());
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let (dir_ino, dir) = r.lookup(b"/bigdir").unwrap();
let report = r.scan();
let misplaced: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("does not lead to"))
.collect();
assert_eq!(misplaced.len(), 1, "{:?}", report.anomalies());
assert_eq!(misplaced[0].category, Category::Directory);
assert_eq!(misplaced[0].location.inode, Some(dir_ino));
let (entry, _) = DirEntry::read_from(&leaf, 1024).unwrap();
assert!(
r.read_dir(&dir)
.unwrap()
.iter()
.any(|e| e.name == entry.name)
);
assert_eq!(r.find_indexed(&dir, &entry.name).unwrap(), Indexed::Absent);
}
#[test]
fn verifies_a_two_level_htree_with_interior_index_nodes() {
let bytes = two_level_directory();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/bigdir").expect("the directory is present");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"an 800-entry directory must be hash-indexed"
);
let block_count = dir.size / 1024;
assert!(
block_count > 124,
"a two-level tree spans more than a one-level root's 123 leaves and its \
root, but this directory is {block_count} blocks — the interior level \
this test exists to exercise was never grown"
);
r.verify_checksums()
.expect("a well-formed two-level htree verifies clean");
assert!(
r.scan().anomalies().is_empty(),
"a clean two-level htree scans clean, got {:?}",
r.scan().anomalies()
);
let names: std::collections::BTreeSet<Vec<u8>> = r
.read_dir(&dir)
.expect("read_dir")
.into_iter()
.filter(|e| e.name != b"." && e.name != b"..")
.map(|e| e.name)
.collect();
assert_eq!(names.len(), 800, "every name survives the two-level index");
}
#[test]
fn an_index_block_whose_limit_cannot_place_its_tail_is_a_fault_not_a_clean_block() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/bigdir".to_vec(), Metadata::new(0o755, time));
for i in 0..200u32 {
let mut name = format!("/bigdir/entry-{i:04}").into_bytes();
name.resize(b"/bigdir/".len() + 100, b'x');
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let root_off = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/bigdir").expect("the directory is present");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"a 200-entry directory must be hash-indexed"
);
r.verify_checksums().expect("clean before the edit");
let bs = 1024usize << r.superblock().log_block_size;
usize::try_from(r.extent_leaves(&dir).unwrap()[0].start).unwrap() * bs
};
put_u16(&mut bytes[root_off..], DX_ROOT_COUNT_OFFSET, 0xffff);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let err = r
.verify_checksums()
.expect_err("an unplaceable tail is a fault");
assert!(
matches!(
err,
ReadError::Parse(ParseError::InvalidField {
structure: "DxCountLimit",
field: "limit",
..
})
),
"{err:?}"
);
}
#[test]
fn the_orphan_files_blocks_carry_their_magic_and_checksum() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let (first_block, blocks) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let ino = r.superblock().orphan_file_inum;
assert_eq!(ino, 12, "the orphan file takes the inode past /lost+found");
let inode = r.inode(ino).unwrap();
assert_eq!(inode.links_count, 1);
assert_eq!(
inode.size,
32 * 4096,
"the size heuristic's floor at 64 MiB"
);
let leaves = r.extent_leaves(&inode).unwrap();
(leaves[0].start, u64::from(leaves[0].len))
};
assert_eq!(blocks, 32, "the file maps as one contiguous run");
{
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.verify_checksums().expect("the orphan tails verify");
assert!(r.scan().anomalies().is_empty());
}
let bs = 4096u64;
let corrupt_at = |offset: u64| {
let mut c = bytes.clone();
c[offset as usize] ^= 0xff;
c
};
let last = first_block + blocks - 1;
let c = corrupt_at((last + 1) * bs - 4);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::ChecksumMismatch {
object: "orphan block",
..
})
));
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.category == Category::Orphan),
"scan reports an Orphan anomaly"
);
let c = corrupt_at((first_block + 1) * bs - 8);
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(matches!(
r.verify_checksums(),
Err(ReadError::BadOrphanFile)
));
let mut c = bytes.clone();
c[1024 + 0x280..1024 + 0x284].copy_from_slice(&0u32.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&c)).unwrap();
assert!(
r.scan()
.anomalies()
.iter()
.any(|a| a.category == Category::Orphan),
"a feature with no file behind it is an Orphan anomaly"
);
}
#[test]
fn a_scan_is_bounded_by_the_bytes_that_exist_not_the_claimed_block_count() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let sb = SuperBlock::read_from(&bytes[1024..2048]).expect("the superblock");
let mut refused = bytes.clone();
crate::ondisk::put_u32(&mut refused[1024 + 0x04..], 0, 0xffff_ffff);
crate::ondisk::put_u32(&mut refused[1024 + 0x150..], 0, 0xffff_ffff);
assert!(matches!(
Reader::open_with(
std::io::Cursor::new(&refused),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.err(),
Some(ReadError::Parse(ParseError::InvalidField {
field: "s_inodes_count",
..
}))
));
let groups = u64::from(u32::MAX / sb.inodes_per_group);
let blocks = groups * u64::from(sb.blocks_per_group);
let mut corrupt = bytes.clone();
crate::ondisk::put_u32(&mut corrupt[1024 + 0x04..], 0, blocks as u32);
crate::ondisk::put_u32(&mut corrupt[1024 + 0x150..], 0, (blocks >> 32) as u32);
crate::ondisk::put_u32(
&mut corrupt[1024..],
0,
(groups * u64::from(sb.inodes_per_group)) as u32,
);
let mut r = Reader::open_with(
std::io::Cursor::new(&corrupt),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
report.anomalies().len() < 1024 && !report.is_truncated(),
"the scan reported {} anomalies for a 64 MiB image claiming {groups} groups — it \
is walking the claimed group count, not the source",
report.anomalies().len()
);
}
#[test]
fn verify_checksums_ignores_a_hostile_free_inode_count() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let mut corrupt = bytes.clone();
crate::ondisk::put_u32(&mut corrupt[1024 + 0x10..], 0, 0xffff_ffff);
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let _ = r.verify_checksums();
let _ = r.scan();
}
#[test]
fn open_rejects_a_bad_superblock() {
let mut bytes = vec![0u8; 4096 * 16];
assert!(matches!(
Reader::open(std::io::Cursor::new(&bytes)),
Err(ReadError::Parse(ParseError::BadMagic { .. }))
));
bytes.truncate(512);
assert!(Reader::open(std::io::Cursor::new(&bytes)).is_err());
}
#[test]
fn multi_group_image_round_trips() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/f".to_vec(),
b"multi-group".to_vec(),
Metadata::new(0o644, time),
);
let image = format(src, 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert_eq!(r.superblock().blocks_count, 131072);
let g3 = r.group_descriptor(3).unwrap();
assert_eq!(g3.block_bitmap, 8);
assert_eq!(g3.inode_table, 1549);
let root = r.inode(2).unwrap();
let f = r
.read_dir(&root)
.unwrap()
.iter()
.find(|e| e.name == b"f")
.unwrap()
.inode;
let f_inode = r.inode(f).unwrap();
assert_eq!(r.read_data(&f_inode).unwrap(), b"multi-group");
}
#[test]
fn a_filesystem_longer_than_its_region_is_found_short_and_one_inside_it_is_not() {
const BASE: u64 = MIB;
let image = format(TreeBuilder::new(), 32 * MIB, opts()).unwrap();
let len = image.as_bytes().len() as u64;
let mut disk = vec![0x9au8; BASE as usize];
disk.extend_from_slice(image.as_bytes());
disk.extend(vec![0xee; MIB as usize]);
let scan = |len: Option<u64>| {
let mut options = OpenOptions::new().base(BASE).policy(ReadPolicy::Lenient);
options.common.len = len;
let mut r = Reader::open_with(std::io::Cursor::new(&disk), &options).expect("open");
let blocks = r.superblock().blocks_count;
let block_size = u64::from(r.feature().block_size);
(r.scan(), blocks, block_size)
};
let (report, blocks, block_size) = scan(Some(16 * MIB));
let short = ReadError::SourceTooShort {
blocks,
held: 16 * MIB / block_size,
}
.anomaly();
assert_eq!(short.severity, Severity::Structural);
assert_eq!(report.anomalies(), [short]);
for len in [Some(len), None] {
let (report, _, _) = scan(len);
assert!(report.is_clean(), "{len:?}: {:?}", report.anomalies());
}
}
#[test]
fn opens_a_filesystem_at_an_arbitrary_offset() {
let time = Timestamp::from_secs(1);
let src = TreeBuilder::new().file(
b"/hi".to_vec(),
b"there".to_vec(),
Metadata::new(0o644, time),
);
let image = format(src, 64 * MIB, opts()).unwrap();
let base = 1_048_576u64; let mut padded = vec![0x9au8; base as usize];
padded.extend_from_slice(image.as_bytes());
let mut r = Reader::open_with(
std::io::Cursor::new(&padded),
&OpenOptions::new().base(base),
)
.unwrap();
assert_eq!(r.policy(), ReadPolicy::Strict);
let root = r.inode(2).unwrap();
let names: Vec<_> = r
.read_dir(&root)
.unwrap()
.into_iter()
.map(|e| e.name)
.collect();
assert!(names.contains(&b"hi".to_vec()));
let hi = r
.walk()
.unwrap()
.into_iter()
.find(|e| e.path == b"/hi")
.unwrap()
.inode;
assert_eq!(r.read_data(&hi).unwrap(), b"there");
assert!(Reader::open(std::io::Cursor::new(&padded)).is_err());
}
#[test]
fn open_with_refuses_a_base_that_overflows_the_superblock_position() {
let src = std::io::Cursor::new(vec![0u8; 4096]);
assert!(matches!(
Reader::open_with(src, &OpenOptions::new().base(u64::MAX).policy(ReadPolicy::Lenient)),
Err(ReadError::OutOfRange {
what: "bytes",
index
}) if index == u64::MAX
));
}
#[test]
fn errors_classify_as_typed_anomalies() {
let a = ReadError::NoSuchInode { inode: 7 }.anomaly();
assert_eq!(a.severity, Severity::Structural);
assert_eq!(a.category, Category::Inode);
assert_eq!(a.location.inode, Some(7));
let cm = ReadError::ChecksumMismatch {
object: "inode",
index: 2,
stored: 1,
computed: 2,
}
.anomaly();
assert_eq!(cm.severity, Severity::Integrity);
assert_eq!(cm.category, Category::Inode);
assert_eq!(cm.location.inode, Some(2));
let oor = ReadError::OutOfRange {
what: "block",
index: 99,
}
.anomaly();
assert_eq!(oor.severity, Severity::Structural);
assert_eq!(oor.category, Category::Superblock);
assert_eq!(oor.location.block, Some(99));
for state in [ReadError::NotCleanlyUnmounted, ReadError::ErrorsDetected] {
let a = state.anomaly();
assert_eq!(a.severity, Severity::Cosmetic, "{state:?}");
assert_eq!(a.category, Category::Superblock, "{state:?}");
}
assert!(ReadPolicy::Strict.is_fatal(Severity::Structural));
assert!(ReadPolicy::Strict.is_fatal(Severity::Integrity));
assert!(ReadPolicy::Strict.is_fatal(Severity::Conformance));
assert!(!ReadPolicy::Strict.is_fatal(Severity::Cosmetic));
assert_eq!(ReadPolicy::default(), ReadPolicy::Strict);
}
#[test]
fn the_state_word_is_read_as_the_last_driver_left_it() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"x".to_vec(), Metadata::new(0o644, time));
let image = format(src, 8 * MIB, opts()).unwrap().into_bytes();
for (state, expected) in [
(STATE_CLEAN, vec![]),
(0, vec![ReadError::NotCleanlyUnmounted]),
(STATE_CLEAN | STATE_ERRORS, vec![ReadError::ErrorsDetected]),
(
STATE_ERRORS,
vec![ReadError::NotCleanlyUnmounted, ReadError::ErrorsDetected],
),
(STATE_CLEAN | 0x0004, vec![]),
(0x0004, vec![ReadError::NotCleanlyUnmounted]),
] {
let mut bytes = image.clone();
put_u16(&mut bytes, 1024 + 0x3a, state);
let sum = superblock_checksum(&bytes[1024..2048]);
bytes[1024 + 0x3fc..1024 + 0x400].copy_from_slice(&sum.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(bytes.as_slice()))
.unwrap_or_else(|e| panic!("state {state:#x}: a strict open: {e}"));
assert_eq!(r.state_on_disk(), state);
let expected: Vec<Anomaly> = expected.iter().map(ReadError::anomaly).collect();
assert_eq!(r.scan().anomalies(), expected, "state {state:#x}");
}
}
#[test]
fn lenient_policy_is_fatal_at_nothing() {
for sev in [
Severity::Cosmetic,
Severity::Conformance,
Severity::Integrity,
Severity::Structural,
] {
assert!(!ReadPolicy::Lenient.is_fatal(sev), "{sev:?} under lenient");
}
assert!(ReadPolicy::Strict.is_fatal(Severity::Structural));
assert!(!ReadPolicy::Strict.is_fatal(Severity::Cosmetic));
assert_eq!(ReadPolicy::default(), ReadPolicy::Strict);
}
#[test]
fn scans_a_clean_multigroup_image_as_clean() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 200_000], m(0o600));
let image = format(src, 512 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let report = r.scan();
assert!(
report.is_clean(),
"unexpected anomalies: {:?}",
report.anomalies()
);
assert_eq!(report.worst_severity(), None);
assert!(!report.has_fatal(ReadPolicy::Strict));
assert!(!report.has_fatal(ReadPolicy::Lenient));
assert_eq!(report.to_report().to_table(), "no findings\n");
assert!(!report.is_truncated());
assert_eq!(
report.to_report().to_json(),
"{\"schema\":3,\"clean\":true,\"count\":0,\"truncated\":false,\"findings\":[],\
\"source_failures\":[]}"
);
}
fn opts_no_csum() -> FormatOptions {
let mut o = opts();
o.feature = FeatureSet::DEFAULT
.with_feature("metadata_csum", false)
.expect("a known name")
.with_feature("metadata_csum_seed", false)
.expect("a known name");
assert_eq!(o.feature.validate(), Ok(()));
o
}
#[test]
fn refuses_an_unsupported_incompat_feature_and_reports_it() {
let clean = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
assert!(Reader::open(std::io::Cursor::new(&clean)).is_ok());
let incompat = 1024 + 0x60;
for (name, byte, mask, want) in [
("dirdata", 1, 0x10u8, 0x1000u32),
("unknown high bit", 3, 0x80u8, 0x8000_0000u32),
] {
let mut bytes = clean.clone();
bytes[incompat + byte] |= mask;
assert_eq!(
Reader::open(std::io::Cursor::new(&bytes)).err(),
Some(ReadError::UnsupportedIncompat { bits: want }),
"a strict open refuses {name}",
);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap_or_else(|_| panic!("a lenient open accepts {name}"));
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Superblock && a.severity == Severity::Structural);
let found = found.unwrap_or_else(|| {
panic!("scan reports {name} as a structural superblock anomaly: {report:?}")
});
assert!(
found.detail.contains(name) || found.detail.contains("0x80000000"),
"the anomaly names the feature it found: {}",
found.detail
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
}
#[test]
fn flags_an_extent_flagged_inode_without_the_extent_feature() {
let src = TreeBuilder::new().file(
b"/hello".to_vec(),
b"world\n".to_vec(),
Metadata::new(0o644, Timestamp::from_secs(1_700_000_000)),
);
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
bytes[1024 + 0x60] &= !0x40;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_extents());
let report = r.scan();
let flagged: Vec<u32> = report
.anomalies()
.iter()
.filter(|a| {
a.category == Category::Inode
&& a.severity == Severity::Structural
&& a.detail.contains("extent format")
})
.filter_map(|a| a.location.inode)
.collect();
assert!(
flagged.contains(&ROOT_INO),
"the root inode is flagged: {report:?}"
);
assert!(
flagged.len() >= 2,
"every extent-mapped inode is flagged: {flagged:?}"
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
fn craft_extent_inode(
bytes: &mut [u8],
number: u32,
mode: u16,
runs: u32,
len: u16,
start: u64,
size: u64,
) {
use crate::ondisk::{EXTENT_ENTRY_SIZE, ExtentHeader, ExtentLeaf};
let mut inode = Inode::empty(256);
inode.mode = mode;
inode.links_count = 1;
inode.flags = InodeFlags::EXTENTS;
inode.size = size;
let header = ExtentHeader {
entries: runs as u16,
max: runs as u16,
depth: 0,
generation: 0,
};
inode.block[..EXTENT_ENTRY_SIZE].copy_from_slice(&header.to_bytes());
for r in 0..runs {
let leaf = ExtentLeaf {
block: r * u32::from(len),
len,
start,
initialized: true,
};
let off = EXTENT_ENTRY_SIZE * (1 + r as usize);
inode.block[off..off + EXTENT_ENTRY_SIZE]
.copy_from_slice(&leaf.to_bytes().expect("a representable run"));
}
let at = inode_offset(bytes, number);
inode
.write_to(&mut bytes[at..at + 256], 256)
.expect("write the crafted inode");
}
#[test]
fn a_directory_mapping_one_block_many_times_is_judged_once_per_block() {
const RUNS: u32 = 4;
const LEN: u16 = 1000;
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(
&mut bytes,
3,
0o040755,
RUNS,
LEN,
2000,
u64::from(u32::MAX),
);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
let shared = ReadError::DirectoryBlocksShared { inode: 3 }.to_string();
assert!(
report.anomalies().iter().any(|a| a.detail == shared),
"the claim past the image is reported"
);
let directory: Vec<_> = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Directory && a.location.inode == Some(3))
.filter(|a| a.detail != shared)
.collect();
let per_block = directory
.iter()
.filter(|a| a.location.block.is_some())
.count();
assert_eq!(
per_block,
LEN as usize,
"one finding per block named, not per logical offset ({} offsets name {LEN} blocks)",
RUNS as usize * LEN as usize
);
assert_eq!(
directory.len() - per_block,
1,
"and one for the directory's framing: {:?}",
directory
.iter()
.filter(|a| a.location.block.is_none())
.collect::<Vec<_>>()
);
assert!(!report.is_truncated(), "this image is fully scanned");
}
#[test]
fn directories_claiming_more_blocks_than_the_image_holds_stop_being_walked() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
for number in 3u32..=10 {
craft_extent_inode(
&mut bytes,
number,
0o040755,
1,
1000,
2000,
u64::from(u32::MAX),
);
}
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
let shared: Vec<_> = report
.anomalies()
.iter()
.filter(|a| {
a.detail
.contains("claim more blocks than the filesystem holds")
})
.collect();
assert_eq!(shared.len(), 1, "{shared:?}");
assert_eq!(shared[0].location.inode, Some(3));
let walked = |n: u32| {
report
.anomalies()
.iter()
.filter(|a| a.location.inode == Some(n) && a.location.block.is_some())
.count()
};
assert_eq!(
walked(3),
1000,
"the directory that passes the bound is walked"
);
assert!((4..=10).all(|n| walked(n) == 0), "and none after it");
}
#[test]
fn a_report_stops_at_its_cap_and_says_so() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
for number in [3u32, 4, 5] {
craft_extent_inode(&mut bytes, number, 0o040755, 4, 4000, 2000, 4000 * 4096);
}
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
report.is_truncated(),
"a report past the cap says it stopped short"
);
assert_eq!(
report.anomalies().len(),
crate::FindingReport::MAX_FINDINGS,
"a truncated report holds exactly the cap"
);
let projected = report.to_report();
assert!(projected.to_json().contains("\"truncated\":true"));
assert!(projected.to_table().contains("report truncated at 10000"));
assert!(
projected
.to_sarif(None)
.contains("\"toolExecutionNotifications\""),
"SARIF records the short run as a notification about the invocation"
);
assert!(report.has_fatal(ReadPolicy::Strict));
let mut tight = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_findings(7)),
)
.unwrap();
let short = tight.scan();
assert!(short.is_truncated());
assert_eq!(short.anomalies().len(), 7);
let notice = "report truncated at 7 findings; the rest of the image was not scanned";
let short = short.to_report();
assert!(short.to_table().contains(notice), "{}", short.to_table());
assert!(short.to_sarif(None).contains(notice));
let mut none = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_findings(0)),
)
.unwrap();
let empty = none.scan();
assert!(empty.is_truncated());
assert!(empty.anomalies().is_empty());
assert!(
!empty.is_clean(),
"a truncated report claimed the image was clean"
);
let empty = empty.to_report();
assert!(empty.to_json().contains("\"clean\":false"));
assert!(empty.to_table().contains("report truncated at 0 findings"));
}
#[test]
fn a_walk_is_bounded_by_the_names_the_source_has_room_for() {
let source = TreeBuilder::new()
.directory(
b"/a".to_vec(),
Metadata::new(0o755, Timestamp::from_secs(0)),
)
.file(
b"/a/f".to_vec(),
b"x".to_vec(),
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut r = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
let full = r.walk().unwrap();
assert!(full.len() >= 3, "{full:?}");
let mut capped = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_walk_entries(2)),
)
.unwrap();
assert!(matches!(
capped.walk(),
Err(ReadError::WalkTooLarge { limit: 2 })
));
}
#[test]
fn the_names_a_walk_has_found_count_against_its_bound_too() {
let time = Timestamp::from_secs(0);
let mut source = TreeBuilder::new();
for n in 0..8u8 {
source = source.file(
format!("/f{n}").into_bytes(),
b"x".to_vec(),
Metadata::new(0o644, time),
);
}
let bytes = format(source, 64 * MIB, opts()).unwrap().into_bytes();
let mut capped = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_walk_entries(3)),
)
.unwrap();
let mut visited = 0usize;
let stopped = capped.walk_with::<ReadError>(|_, _| {
visited += 1;
Ok(())
});
assert!(matches!(stopped, Err(ReadError::WalkTooLarge { limit: 3 })));
assert_eq!(visited, 0, "the walk stopped before it spent the memory");
}
#[test]
fn the_bounds_are_measured_from_the_filesystem_and_not_from_the_source() {
const BASE: usize = 1 << 20;
const TRAILING: usize = 3 << 20;
let source = TreeBuilder::new().file(
b"/f".to_vec(),
b"x".to_vec(),
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 8 * MIB, opts()).unwrap().into_bytes();
let mut disk = vec![0u8; BASE];
disk.extend_from_slice(&image);
disk.extend_from_slice(&vec![0u8; TRAILING]);
let mut r = Reader::open_with(
std::io::Cursor::new(&disk),
&OpenOptions::new().base(BASE as u64),
)
.unwrap();
assert_eq!(
r.source_len(),
(image.len() + TRAILING) as u64,
"what is in front of the filesystem is not the filesystem's to be bounded by"
);
assert!(r.walk().unwrap().iter().any(|e| e.path == b"/f"));
}
#[test]
fn a_window_takes_only_the_extent_leaves_it_falls_in() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/f".to_vec(),
vec![b'x'; 64 * 4096],
Metadata::new(0o644, time),
);
let bytes = format(src, 16 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
assert!(
!r.extent_leaves_in(&inode, 0..64).unwrap().is_empty(),
"the file's own blocks are in the window that covers them"
);
assert!(
r.extent_leaves_in(&inode, 1_000..1_064).unwrap().is_empty(),
"a window past everything the file maps takes no leaf"
);
assert_eq!(
r.extent_leaves(&inode).unwrap(),
r.extent_leaves_in(&inode, 0..u64::MAX).unwrap()
);
}
#[test]
fn a_directory_answers_to_the_walk_cap_and_reads_each_of_its_blocks_once() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..64 {
src = src.file(
format!("/d/f{i:03}").into_bytes(),
b"x".to_vec(),
Metadata::new(0o644, time),
);
}
let bytes = format(src, 16 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_walk_entries(8)),
)
.unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
assert!(
matches!(r.read_dir(&dir), Err(ReadError::WalkTooLarge { limit: 8 })),
"one directory answers to the cap where it is read"
);
let mut r = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
let names: Vec<Vec<u8>> = r
.read_dir(&dir)
.unwrap()
.into_iter()
.map(|e| e.name)
.collect();
let unique: HashSet<&Vec<u8>> = names.iter().collect();
assert_eq!(names.len(), unique.len(), "a name is listed once");
}
#[test]
fn a_walk_stops_at_a_path_longer_than_a_walk_builds() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new();
let mut path = String::new();
for i in 0..120 {
path.push('/');
path.push_str(&format!("{i:03}-a-component-of-substantial-length"));
src = src.directory(path.clone().into_bytes(), Metadata::new(0o755, time));
}
assert!(
path.len() > 4096,
"the fixture reaches past a path's length"
);
let bytes = format(src, 32 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(
matches!(r.walk(), Err(ReadError::PathTooLong { limit: 4096 })),
"a walk that would build a path past the bound stops instead"
);
}
#[test]
fn a_symlink_target_is_bounded_by_what_a_path_can_be() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().symlink(
b"/link".to_vec(),
vec![b'a'; 200],
Metadata::new(0o777, time),
);
let mut bytes = format(src, 16 * MIB, opts_no_csum()).unwrap().into_bytes();
let number = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (number, inode) = r.lookup_no_follow(b"/link").unwrap();
assert_eq!(r.read_symlink(&inode).unwrap().len(), 200);
number
};
let at = inode_offset(&bytes, number);
crate::ondisk::put_u32(&mut bytes[at..], 4, 400 << 20);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, inode) = r.lookup_no_follow(b"/link").unwrap();
assert!(
matches!(
r.read_symlink(&inode),
Err(ReadError::FileTooLarge { limit: 4096, .. })
),
"a target longer than a path can be is refused before it is read"
);
}
#[test]
fn the_shared_frame_reads_bytes_only_from_a_regular_file() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/d".to_vec(), m(0o755))
.file(b"/d/f".to_vec(), b"contents".to_vec(), m(0o644))
.symlink(b"/slow".to_vec(), vec![b'a'; 200], m(0o777))
.fifo(b"/pipe".to_vec(), m(0o644));
let bytes = format(src, 16 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let mut buf = [0u8; 4096];
for path in [&b"/d"[..], b"/slow", b"/pipe"] {
let (_, inode) = r.lookup_no_follow(path).unwrap();
let filled = <Reader<_> as FsTree>::read_bytes(&mut r, &inode, 0, &mut buf).unwrap();
assert_eq!(
filled,
0,
"{} yields no bytes",
String::from_utf8_lossy(path)
);
}
let (_, file) = r.lookup_no_follow(b"/d/f").unwrap();
let filled = <Reader<_> as FsTree>::read_bytes(&mut r, &file, 0, &mut buf).unwrap();
assert_eq!(&buf[..filled], b"contents");
}
#[cfg(feature = "tar")]
#[test]
fn a_file_the_image_cannot_read_stops_an_archive_as_the_images_failure() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/f".to_vec(),
vec![7u8; 10_000],
Metadata::new(0o644, time),
);
let mut bytes = format(src, 16 * MIB, opts_no_csum()).unwrap().into_bytes();
let number = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.lookup_no_follow(b"/f").unwrap().0
};
let at = inode_offset(&bytes, number) + 40;
bytes[at] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let err = crate::ArchiveSink::new(Vec::new())
.write_tree(&mut r)
.unwrap_err();
assert!(
matches!(err, crate::ArchiveError::Read(TreeError::Malformed { .. })),
"{err:?}"
);
}
#[test]
fn a_file_read_is_capped_only_where_a_caller_asks() {
let source = TreeBuilder::new().file(
b"/f".to_vec(),
vec![7u8; 8192],
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut r = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
assert_eq!(r.read_data(&inode).unwrap().len(), 8192);
let mut capped = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().limits(Limits::new().max_file_bytes(100)),
)
.unwrap();
let (_, inode) = capped.lookup(b"/f").unwrap();
assert!(matches!(
capped.read_data(&inode),
Err(ReadError::FileTooLarge {
size: 8192,
limit: 100
})
));
let mut sink = Vec::new();
assert!(matches!(
capped.read_data_to(&inode, &mut sink),
Err(ReadError::FileTooLarge { .. })
));
assert!(sink.is_empty(), "nothing is written before the refusal");
let mut buf = [0u8; 100];
assert_eq!(capped.read_into(&inode, 0, &mut buf).unwrap(), 100);
assert_eq!(buf, [7u8; 100]);
}
#[test]
fn a_capped_read_never_maps_the_claim_behind_it() {
const CLAIM: u64 = 1 << 44; let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, CLAIM);
for cap in [0u64, 10, 8192] {
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new()
.policy(ReadPolicy::Lenient)
.limits(Limits::new().max_file_bytes(cap)),
)
.unwrap();
let inode = r.inode(12).unwrap();
assert!(
matches!(
r.read_data(&inode),
Err(ReadError::FileTooLarge { size: CLAIM, .. })
),
"a {CLAIM}-byte claim must be refused under a {cap}-byte cap"
);
}
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let inode = r.inode(12).unwrap();
let mut buf = [0u8; 4096];
assert_eq!(r.read_into(&inode, 0, &mut buf).unwrap(), 4096);
}
#[test]
fn a_ranged_read_reads_the_window_it_is_given() {
for label in ["extent", "block-mapped"] {
let mut o = opts();
if label == "block-mapped" {
o.feature = FeatureSet::EXT2;
}
let mut contents = Vec::new();
for block in 0..20u8 {
contents.extend(std::iter::repeat_n(block, 4096));
}
let source = TreeBuilder::new().file(
b"/f".to_vec(),
contents.clone(),
Metadata::new(0o644, Timestamp::from_secs(0)),
);
let image = format(source, 64 * MIB, o).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, inode) = r.lookup(b"/f").unwrap();
assert_eq!(
r.read_data(&inode).unwrap(),
contents,
"{label}: whole file"
);
for (offset, len) in [
(0usize, 10usize),
(4090, 12),
(65536, 8192),
(4096 * 19, 4096),
] {
let mut buf = vec![0u8; len];
let filled = r.read_into(&inode, offset as u64, &mut buf).unwrap();
assert_eq!(filled, len, "{label}: {len} bytes at {offset}");
assert_eq!(&buf[..filled], &contents[offset..offset + len]);
}
let mut buf = vec![0u8; 4096];
let filled = r
.read_into(&inode, contents.len() as u64 - 10, &mut buf)
.unwrap();
assert_eq!(filled, 10, "{label}: a read at the end is short");
assert_eq!(
r.read_into(&inode, contents.len() as u64, &mut buf)
.unwrap(),
0,
"{label}: a read past the end fills nothing"
);
let mut sink = Vec::new();
assert_eq!(
r.read_data_to(&inode, &mut sink).unwrap(),
contents.len() as u64
);
assert_eq!(sink, contents, "{label}: streamed bytes");
}
}
#[test]
fn a_ranged_read_of_a_sparse_file_reads_holes_as_zeros() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, 4 * 4096);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let inode = r.inode(12).unwrap();
let mut buf = vec![0xffu8; 8192];
let filled = r.read_into(&inode, 4096, &mut buf).unwrap();
assert_eq!(filled, 8192);
assert!(
buf.iter().all(|&b| b == 0),
"a hole reads as zeros, overwriting the buffer's previous contents"
);
}
#[test]
fn a_walk_with_visits_every_name_without_gathering_them() {
let time = Timestamp::from_secs(0);
let source = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, time))
.file(
b"/etc/hostname".to_vec(),
b"host\n".to_vec(),
Metadata::new(0o644, time),
)
.directory(b"/usr".to_vec(), Metadata::new(0o755, time))
.file(
b"/usr/x".to_vec(),
b"x".to_vec(),
Metadata::new(0o644, time),
);
let image = format(source, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let gathered: Vec<Vec<u8>> = r.walk().unwrap().into_iter().map(|e| e.path).collect();
let mut streamed = Vec::new();
let mut bytes_seen = 0u64;
r.walk_with::<ReadError>(|reader, entry| {
if entry.inode.mode & 0o170000 == 0o100000 {
bytes_seen += reader.read_data(&entry.inode)?.len() as u64;
}
streamed.push(entry.path);
Ok(())
})
.unwrap();
assert_eq!(streamed, gathered);
assert_eq!(bytes_seen, 6, "hostname's five bytes and x's one");
let mut count = 0usize;
let stopped = r.walk_with::<ReadError>(|_, _| {
count += 1;
if count == 2 {
return Err(ReadError::BadJournal);
}
Ok(())
});
assert!(matches!(stopped, Err(ReadError::BadJournal)));
assert_eq!(count, 2, "the walk stops at the failing entry");
let mut capped = Reader::open_with(
std::io::Cursor::new(image.as_bytes()),
&OpenOptions::new().limits(Limits::new().max_walk_entries(2)),
)
.unwrap();
assert!(matches!(
capped.walk_with::<ReadError>(|_, _| Ok(())),
Err(ReadError::WalkTooLarge { limit: 2 })
));
}
#[test]
fn a_named_seed_overrides_the_one_the_image_implies() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let bytes = image.into_bytes();
let mut own = Reader::open_with(std::io::Cursor::new(&bytes), &OpenOptions::new()).unwrap();
own.verify_checksums()
.expect("the image verifies against its own seed");
let mut wrong = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().csum_seed(0xdead_beef),
)
.unwrap();
assert!(
matches!(
wrong.verify_checksums(),
Err(ReadError::ChecksumMismatch { .. })
),
"a seed the image's checksums were not computed from must not verify"
);
}
#[test]
fn the_journal_and_orphan_file_are_read_within_the_image_they_claim_to_be_in() {
const CLAIM: u64 = 1 << 44; let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
craft_extent_inode(&mut bytes, 8, 0o100600, 1, 4, 2000, CLAIM);
craft_extent_inode(&mut bytes, 12, 0o100600, 1, 4, 2000, CLAIM);
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert_eq!(r.superblock().journal_inum, 8);
assert_eq!(r.superblock().orphan_file_inum, 12);
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Orphan),
"the orphan file's claim is faulted: {}",
report.to_report().to_table()
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Journal),
"the journal's first block is judged: {}",
report.to_report().to_table()
);
assert!(matches!(
r.journal_superblock(),
Err(ReadError::Parse(_) | ReadError::BadJournal)
));
}
#[test]
fn flags_an_attribute_block_without_the_ext_attr_feature() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new()
.file(b"/f".to_vec(), b"data".to_vec(), Metadata::new(0o644, time))
.xattr(b"user.big".to_vec(), vec![0xAB; 2000]);
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_ext_attr());
assert!(
r.scan().is_clean(),
"the image is coherent while the feature stands"
);
}
bytes[1024 + 0x5c] &= !0x08;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_ext_attr());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.category == Category::Xattr && a.detail.contains("attribute block"))
.unwrap_or_else(|| panic!("the orphaned attribute block is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Structural);
assert!(found.location.inode.is_some() && found.location.block.is_some());
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_a_large_regular_file_without_the_large_file_feature() {
let mut bytes = format(TreeBuilder::new(), 64 * MIB, opts_no_csum())
.unwrap()
.into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_large_file());
assert!(r.scan().is_clean());
}
bytes[1024 + 0x64] &= !0x02;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_large_file());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("regular file"))
.unwrap_or_else(|| panic!("the large file is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Inode);
assert_eq!(
found.location.inode,
Some(7),
"the resize inode is the file that reaches the bound"
);
assert_eq!(
report
.anomalies()
.iter()
.filter(|a| a.detail.contains("regular file"))
.count(),
1
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_an_indexed_directory_without_the_dir_index_feature() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..600u32 {
let name = format!("/d/entry-{i:04}-padded-out-to-force-an-index").into_bytes();
src = src.file(name, Vec::new(), Metadata::new(0o644, time));
}
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_dir_index());
let (_, dir) = r.lookup(b"/d").expect("the directory");
assert!(
dir.flags.contains(InodeFlags::INDEX),
"the directory is large enough to be indexed"
);
assert!(r.scan().is_clean());
}
bytes[1024 + 0x5c] &= !0x20;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_dir_index());
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("hash-indexed"))
.unwrap_or_else(|| panic!("the unadvertised index is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Directory);
assert!(found.location.inode.is_some());
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn flags_the_hash_index_flag_on_something_that_is_not_a_directory() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), b"data".to_vec(), Metadata::new(0o644, time));
let mut bytes = format(src, 64 * MIB, opts_no_csum()).unwrap().into_bytes();
let (number, _) = {
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_dir_index());
assert!(r.scan().is_clean());
r.lookup(b"/f").expect("the file")
};
let at = inode_offset(&bytes, number) + 0x20;
bytes[at + 1] |= 0x10;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let file = r.inode(number).unwrap();
assert!(file.flags.contains(InodeFlags::INDEX));
let report = r.scan();
let found = report
.anomalies()
.iter()
.find(|a| a.detail.contains("not a directory"))
.unwrap_or_else(|| panic!("the flag on a non-directory is flagged: {report:?}"));
assert_eq!(found.severity, Severity::Conformance);
assert_eq!(found.category, Category::Inode);
assert_eq!(found.location.inode, Some(number));
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("does not enable the dir_index feature")),
"a regular file was described as a hash-indexed directory: {report:?}"
);
bytes[1024 + 0x5c] &= !0x20;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let report = r.scan();
assert!(
!report
.anomalies()
.iter()
.any(|a| a.detail.contains("does not enable the dir_index feature")),
"{report:?}"
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.detail.contains("not a directory"))
);
}
#[test]
fn the_dirent_bound_is_the_shortest_record_the_format_encodes() {
assert_eq!(MIN_DIRENT_LEN, u64::from(crate::ondisk::min_rec_len(1)));
assert!(MIN_DIRENT_LEN <= u64::from(crate::ondisk::min_rec_len(255)));
}
#[test]
fn flags_metadata_outside_its_group_without_flex_bg() {
let image = format(TreeBuilder::new(), 256 * MIB, opts_no_csum()).unwrap();
let mut bytes = image.into_bytes();
{
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(r.feature().has_flex_bg());
assert!(
r.scan().is_clean(),
"a flex image places metadata legally: {:?}",
r.scan().anomalies()
);
}
bytes[1024 + 0x60 + 1] &= !0x02;
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert!(!r.feature().has_flex_bg());
let report = r.scan();
let outside: Vec<&Anomaly> = report
.anomalies()
.iter()
.filter(|a| a.detail.contains("outside the group"))
.collect();
assert!(
!outside.is_empty(),
"the packed metadata is now out of place: {report:?}"
);
assert!(
outside.iter().any(|a| {
a.location.group == Some(1)
&& a.category == Category::Bitmap
&& a.severity == Severity::Structural
}),
"group 1's bitmap is flagged as outside its group: {report:?}"
);
assert!(report.has_fatal(ReadPolicy::Strict));
}
#[test]
fn scan_collects_multiple_anomalies_and_renders_a_table() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(
b"/hostname".to_vec(),
b"ferrosys\n".to_vec(),
Metadata::new(0o644, time),
);
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let root_off = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
r.group_descriptor(0).unwrap().inode_table as usize * 4096 + 256
};
let mut corrupt = bytes.clone();
corrupt[1024 + 0x30] ^= 0xff; corrupt[root_off] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock && a.severity == Severity::Integrity)
);
assert!(
report
.anomalies()
.iter()
.any(|a| a.category == Category::Inode
&& a.severity == Severity::Integrity
&& a.location.inode == Some(2))
);
assert!(report.anomalies().len() >= 2);
assert_eq!(report.worst_severity(), Some(Severity::Integrity));
assert!(report.has_fatal(ReadPolicy::Strict));
assert!(!report.has_fatal(ReadPolicy::Lenient));
let table = report.to_report().to_table();
let mut lines = table.lines();
let header = lines.next().unwrap();
assert!(header.starts_with("SEVERITY"));
assert!(
header.contains("CATEGORY") && header.contains("LOCATION") && header.contains("DETAIL")
);
assert_eq!(lines.count(), report.anomalies().len());
assert!(table.contains("integrity"));
assert!(table.contains("inode 2"));
}
#[test]
fn scan_files_an_out_of_range_extent_against_the_extent_tree() {
let time = Timestamp::from_secs(1_700_000_000);
let src =
TreeBuilder::new().file(b"/f".to_vec(), vec![0x42; 4096], Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, inode_off) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (n, _) = r.lookup(b"/f").expect("lookup /f");
let isize = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
(n, table * 4096 + (n as usize - 1) * isize)
};
let bogus = 0x00ff_ffffu32; let mut corrupt = bytes.clone();
corrupt[inode_off + 0x3c..inode_off + 0x40].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let extent = report
.anomalies()
.iter()
.find(|a| a.category == Category::ExtentTree)
.expect("an out-of-range extent is filed against the extent tree");
assert_eq!(extent.location.inode, Some(ino));
assert_eq!(extent.location.block, Some(u64::from(bogus)));
assert_eq!(extent.severity, Severity::Structural);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range block was mis-filed against the superblock"
);
}
#[test]
fn scan_files_an_out_of_range_bitmap_block_against_the_bitmap() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let desc_off = 4096;
let bogus = 0x00ff_ffffu32; let mut corrupt = bytes.clone();
corrupt[desc_off..desc_off + 4].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let bitmap = report
.anomalies()
.iter()
.find(|a| a.category == Category::Bitmap && a.location.block == Some(u64::from(bogus)))
.expect("an out-of-range bitmap block is filed against the bitmap");
assert_eq!(bitmap.location.group, Some(0));
assert_eq!(bitmap.severity, Severity::Structural);
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range bitmap block was mis-filed against the superblock"
);
}
#[test]
fn scan_files_an_out_of_range_xattr_block_against_the_attribute_block() {
let time = Timestamp::from_secs(1_700_000_000);
let src = TreeBuilder::new().file(b"/f".to_vec(), Vec::new(), Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (ino, inode_off) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (n, _) = r.lookup(b"/f").expect("lookup /f");
let isize = r.superblock().inode_size as usize;
let table = r.group_descriptor(0).unwrap().inode_table as usize;
(n, table * 4096 + (n as usize - 1) * isize)
};
let bogus = 0x00ff_ffffu32;
let mut corrupt = bytes.clone();
corrupt[inode_off + 0x68..inode_off + 0x6c].copy_from_slice(&bogus.to_le_bytes());
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let xattr = report
.anomalies()
.iter()
.find(|a| a.category == Category::Xattr && a.location.block == Some(u64::from(bogus)))
.expect("an out-of-range xattr block is filed against the attribute block");
assert_eq!(xattr.location.inode, Some(ino));
assert!(
!report
.anomalies()
.iter()
.any(|a| a.category == Category::Superblock),
"the out-of-range xattr block was mis-filed against the superblock"
);
}
#[test]
fn scan_collects_both_bitmap_faults_in_one_group() {
let bytes = format(TreeBuilder::new(), 64 * MIB, opts())
.unwrap()
.into_bytes();
let (block_bmp, inode_bmp) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let d = r.group_descriptor(0).unwrap();
(d.block_bitmap, d.inode_bitmap)
};
let mut corrupt = bytes.clone();
corrupt[block_bmp as usize * 4096] ^= 0xff;
corrupt[inode_bmp as usize * 4096] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let bitmap_faults = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Bitmap)
.count();
assert_eq!(
bitmap_faults,
2,
"both bitmaps of the group fault, so both are reported, got {:?}",
report.anomalies()
);
}
#[test]
fn scan_collects_multiple_faults_in_one_directory() {
let time = Timestamp::from_secs(1_700_000_000);
let mut src = TreeBuilder::new().directory(b"/d".to_vec(), Metadata::new(0o755, time));
for i in 0..300u32 {
src = src.file(
format!("/d/file-{i:04}").into_bytes(),
Vec::new(),
Metadata::new(0o644, time),
);
}
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (first, nblocks) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let (_, dir) = r.lookup(b"/d").unwrap();
let leaves = r.extent_leaves(&dir).unwrap();
(leaves[0].start, dir.size / 4096)
};
assert!(nblocks >= 3, "the directory must span several blocks");
let mut corrupt = bytes.clone();
corrupt[(first + 1) as usize * 4096 + 40] ^= 0xff;
corrupt[(first + 2) as usize * 4096 + 40] ^= 0xff;
let mut r = Reader::open(std::io::Cursor::new(&corrupt)).unwrap();
let report = r.scan();
let dir_faults = report
.anomalies()
.iter()
.filter(|a| a.category == Category::Directory)
.count();
assert_eq!(
dir_faults,
2,
"both corrupt directory blocks are reported, got {:?}",
report.anomalies()
);
}
#[test]
fn extent_tail_offset_follows_the_declared_capacity() {
use crate::extent::node_capacity;
const BS: usize = 4096;
let node = |eh_max: usize| {
let mut n = vec![0u8; BS];
put_u16(&mut n, 4, eh_max as u16); n
};
assert_eq!(
extent_tail_offset(&node(node_capacity(BS)), BS),
tail_offset(BS)
);
assert_eq!(
extent_tail_offset(&node(node_capacity(BS) - 1), BS),
tail_offset(BS) - EXTENT_ENTRY_SIZE
);
assert_eq!(extent_tail_offset(&node(0xffff), BS), tail_offset(BS));
}
#[test]
fn an_anomaly_projects_into_the_shared_finding_frame() {
let a = Anomaly {
severity: Severity::Structural,
category: Category::ExtentTree,
location: Location {
block: Some(99),
group: None,
inode: Some(12),
},
detail: "bad node".to_string(),
};
let f = a.to_finding(4096);
assert_eq!(f.severity, Severity::Structural);
assert_eq!(f.family, Family::Ext);
assert_eq!(f.category, "extent tree");
assert_eq!(f.offset, Some(99 * 4096));
assert_eq!(
f.coordinates,
vec![
(std::borrow::Cow::Borrowed("inode"), 12),
(std::borrow::Cow::Borrowed("block"), 99),
]
);
let no_block = Anomaly {
severity: Severity::Cosmetic,
category: Category::Journal,
location: Location::default(),
detail: "x".to_string(),
};
let f = no_block.to_finding(4096);
assert_eq!(f.offset, None);
assert!(f.coordinates.is_empty());
}
#[test]
fn a_block_number_no_image_could_hold_names_no_offset() {
let a = Anomaly {
severity: Severity::Structural,
category: Category::Directory,
location: Location {
block: Some(u64::MAX),
..Location::default()
},
detail: "out of range".to_string(),
};
let f = a.to_finding(4096);
assert_eq!(f.offset, None);
assert_eq!(
f.coordinates,
vec![(std::borrow::Cow::Borrowed("block"), u64::MAX)]
);
}
fn golden_report() -> ScanReport {
ScanReport::new(
vec![
Anomaly {
severity: Severity::Integrity,
category: Category::Inode,
location: Location {
block: Some(40),
group: Some(3),
inode: Some(12),
},
detail: "checksum \"bad\"".to_string(),
},
Anomaly {
severity: Severity::Cosmetic,
category: Category::Journal,
location: Location::default(),
detail: "note".to_string(),
},
],
false,
crate::FindingReport::MAX_FINDINGS,
4096,
)
}
#[test]
fn the_findings_document_is_a_versioned_golden_shape() {
assert_eq!(
golden_report().to_report().to_json(),
"{\"schema\":3,\"clean\":false,\"count\":2,\"truncated\":false,\"findings\":[\
{\"severity\":\"integrity\",\"family\":\"ext\",\"category\":\"inode\",\
\"offset\":163840,\"location\":{\"group\":3,\"inode\":12,\"block\":40},\
\"detail\":\"checksum \\\"bad\\\"\"},\
{\"severity\":\"cosmetic\",\"family\":\"ext\",\"category\":\"journal\",\
\"location\":{},\"detail\":\"note\"}],\"source_failures\":[]}"
);
assert_eq!(
golden_report().to_report().to_table(),
"SEVERITY CATEGORY LOCATION DETAIL\n\
integrity inode group 3 inode 12 block 40 checksum \"bad\"\n\
cosmetic journal - note\n"
);
let clean = ScanReport::default().to_report();
assert_eq!(
clean.to_json(),
"{\"schema\":3,\"clean\":true,\"count\":0,\"truncated\":false,\"findings\":[],\
\"source_failures\":[]}"
);
assert_eq!(clean.to_table(), "no findings\n");
assert_eq!(crate::finding::FINDINGS_SCHEMA_VERSION, 3);
let failed = ScanReport::new(
vec![
ReadError::Io {
kind: std::io::ErrorKind::Other,
message: "the medium failed".to_string(),
}
.anomaly(),
golden_report().anomalies()[1].clone(),
],
false,
crate::FindingReport::MAX_FINDINGS,
4096,
);
assert_eq!(failed.anomalies().len(), 1);
assert_eq!(failed.source_failures().len(), 1);
assert_eq!(failed.worst_severity(), Some(Severity::Cosmetic));
assert!(!failed.is_clean());
let projected = failed.to_report();
assert_eq!(
projected.to_json(),
"{\"schema\":3,\"clean\":false,\"count\":1,\"truncated\":false,\"findings\":[\
{\"severity\":\"cosmetic\",\"family\":\"ext\",\"category\":\"journal\",\
\"location\":{},\"detail\":\"note\"}],\"source_failures\":[\
{\"severity\":\"structural\",\"family\":\"ext\",\"category\":\"source\",\
\"location\":{},\"detail\":\"i/o error: the medium failed\"}]}"
);
assert_eq!(
projected.to_table(),
"SEVERITY CATEGORY LOCATION DETAIL\n\
cosmetic journal - note\n\
\n\
source failure: i/o error: the medium failed\n"
);
assert!(projected.to_sarif(None).contains(
"{\"executionSuccessful\":false,\"toolExecutionNotifications\":[\
{\"level\":\"error\",\"message\":{\"text\":\"source failure: i/o error: the \
medium failed\"}}]}"
));
let short = ReadError::Io {
kind: std::io::ErrorKind::UnexpectedEof,
message: "failed to fill whole buffer".to_string(),
}
.anomaly();
assert_eq!(
(short.severity, short.category),
(Severity::Structural, Category::Superblock)
);
}
#[test]
fn the_findings_document_projects_to_sarif() {
assert_eq!(
ScanReport::default().to_report().to_sarif(None),
"{\"$schema\":\"https://json.schemastore.org/sarif-2.1.0.json\",\
\"version\":\"2.1.0\",\"runs\":[{\"tool\":{\"driver\":{\"name\":\"ferrosys\",\
\"rules\":[]}},\"results\":[]}]}"
);
let expected = String::from(
"{\"$schema\":\"https://json.schemastore.org/sarif-2.1.0.json\",\
\"version\":\"2.1.0\",\"runs\":[{\"tool\":{\"driver\":{\"name\":\"ferrosys\",\"rules\":[",
) + "{\"id\":\"ext/inode\",\"name\":\"ext/inode\",\"shortDescription\":{\"text\":\"ext inode finding\"}},"
+ "{\"id\":\"ext/journal\",\"name\":\"ext/journal\",\"shortDescription\":{\"text\":\"ext journal finding\"}}"
+ "]}},\"results\":["
+ "{\"ruleId\":\"ext/inode\",\"level\":\"error\",\"message\":{\"text\":\"checksum \\\"bad\\\"\"},"
+ "\"locations\":[{\"physicalLocation\":{\"artifactLocation\":{\"uri\":\"disk.img\"},"
+ "\"address\":{\"absoluteAddress\":163840}},"
+ "\"logicalLocations\":[{\"fullyQualifiedName\":\"group 3 inode 12 block 40\"}]}],"
+ "\"properties\":{\"severity\":\"integrity\",\"family\":\"ext\",\"category\":\"inode\","
+ "\"offset\":163840,\"group\":3,\"inode\":12,\"block\":40}},"
+ "{\"ruleId\":\"ext/journal\",\"level\":\"note\",\"message\":{\"text\":\"note\"},"
+ "\"locations\":[{\"physicalLocation\":{\"artifactLocation\":{\"uri\":\"disk.img\"}}}],"
+ "\"properties\":{\"severity\":\"cosmetic\",\"family\":\"ext\",\"category\":\"journal\"}}"
+ "]}]}";
assert_eq!(
golden_report().to_report().to_sarif(Some("disk.img")),
expected
);
let bare = ScanReport::new(
vec![Anomaly {
severity: Severity::Conformance,
category: Category::Superblock,
location: Location::default(),
detail: "x".to_string(),
}],
false,
crate::FindingReport::MAX_FINDINGS,
4096,
);
assert!(bare.to_report().to_sarif(None).contains(
"\"ruleId\":\"ext/superblock\",\"level\":\"warning\",\"message\":{\"text\":\"x\"},\
\"properties\":{\"severity\":\"conformance\",\"family\":\"ext\",\"category\":\"superblock\"}"
));
}
fn needing_recovery() -> (Vec<u8>, usize) {
use crate::bytes::put_u32_be;
let image = format(TreeBuilder::new(), 16 * MIB, opts())
.unwrap()
.into_bytes();
let mut r = Reader::open(std::io::Cursor::new(image.as_slice())).unwrap();
let jsb = usize::try_from(r.journal_superblock_block().unwrap().unwrap()).unwrap();
let bs = r.block_size;
drop(r);
let mut bytes = image;
let at = |n: usize| (jsb + n) * bs;
put_u32_be(&mut bytes, at(0) + crate::journal::offset::START, 1);
let header = |b: &mut Vec<u8>, at: usize, kind: u32, seq: u32| {
put_u32_be(b, at, crate::journal::JBD2_MAGIC);
put_u32_be(b, at + 4, kind);
put_u32_be(b, at + 8, seq);
};
header(&mut bytes, at(1), crate::journal::BLOCKTYPE_DESCRIPTOR, 1);
put_u32_be(&mut bytes, at(1) + 12, 3000);
put_u32_be(&mut bytes, at(1) + 16, 0);
put_u32_be(&mut bytes, at(1) + 36, 3001);
put_u32_be(
&mut bytes,
at(1) + 40,
crate::journal::TAG_SAME_UUID | crate::journal::TAG_LAST,
);
bytes[at(2)..at(3)].fill(0xa1);
bytes[at(3)..at(4)].fill(0xa2);
header(&mut bytes, at(4), crate::journal::BLOCKTYPE_COMMIT, 1);
header(&mut bytes, at(5), crate::journal::BLOCKTYPE_REVOKE, 2);
put_u32_be(&mut bytes, at(5) + 12, 20);
put_u32_be(&mut bytes, at(5) + 16, 3000);
header(&mut bytes, at(6), crate::journal::BLOCKTYPE_DESCRIPTOR, 2);
put_u32_be(&mut bytes, at(6) + 12, 3002);
put_u32_be(&mut bytes, at(6) + 16, crate::journal::TAG_LAST);
bytes[at(7)..at(8)].fill(0xa3);
header(&mut bytes, at(8), crate::journal::BLOCKTYPE_COMMIT, 2);
let incompat = crate::bytes::get_u32(&bytes, 1024 + SuperBlock::FEATURE_INCOMPAT_OFFSET);
crate::bytes::put_u32(
&mut bytes,
1024 + SuperBlock::FEATURE_INCOMPAT_OFFSET,
incompat | INCOMPAT_RECOVER,
);
let sum = superblock_checksum(&bytes[1024..2048]);
crate::bytes::put_u32(&mut bytes, 1024 + SuperBlock::CHECKSUM_OFFSET, sum);
(bytes, jsb)
}
#[test]
fn a_journal_longer_than_the_image_holds_is_refused_before_its_log_is_walked() {
use crate::bytes::put_u32_be;
let (mut bytes, jsb) = needing_recovery();
let bs = 4096;
let at = inode_offset(&bytes, 8);
put_u32_be(
&mut bytes,
jsb * bs + crate::journal::offset::MAX_LEN,
1_000_000,
);
let size: u64 = 1_000_000 * bs as u64;
crate::bytes::put_u32(&mut bytes, at + 0x04, size as u32);
crate::bytes::put_u32(&mut bytes, at + 0x6C, (size >> 32) as u32);
let opened = Reader::open(std::io::Cursor::new(bytes.as_slice()));
assert!(
matches!(
opened,
Err(ReadError::JournalMalformed {
detail: "a journal longer than the file holding it",
..
})
),
"{:?}",
opened.err()
);
}
#[test]
fn needing_recovery_without_a_journal_is_malformed() {
let (mut bytes, _) = needing_recovery();
let at = 1024 + 0x5C;
let compat = crate::bytes::get_u32(&bytes, at);
crate::bytes::put_u32(&mut bytes, at, compat & !0x4);
let sum = superblock_checksum(&bytes[1024..2048]);
crate::bytes::put_u32(&mut bytes, 1024 + SuperBlock::CHECKSUM_OFFSET, sum);
let opened = Reader::open(std::io::Cursor::new(bytes.as_slice()));
assert!(
matches!(opened, Err(ReadError::JournalMalformed { .. })),
"{:?}",
opened.err()
);
}
#[test]
fn a_forged_log_is_replayed_over_the_homes() {
let (bytes, _) = needing_recovery();
let mut r = Reader::open(std::io::Cursor::new(bytes.as_slice())).expect("open");
assert!(r.needs_recovery());
let replay = *r.journal_replay().expect("replayed");
assert_eq!(
(replay.transactions, replay.blocks, replay.skipped),
(2, 2, 0)
);
assert_eq!(r.read_block(3000).unwrap(), bytes[3000 * 4096..3001 * 4096]);
assert!(r.read_block(3001).unwrap().iter().all(|&b| b == 0xa2));
assert!(r.read_block(3002).unwrap().iter().all(|&b| b == 0xa3));
let mut span = vec![0u8; 3 * 4096];
let got = r.read_at(3000 * 4096 + 100, span.len()).unwrap();
span.copy_from_slice(&got);
assert_eq!(span[..4096 - 100], bytes[3000 * 4096 + 100..3001 * 4096]);
assert!(span[4096 - 100..2 * 4096 - 100].iter().all(|&b| b == 0xa2));
assert!(span[2 * 4096 - 100..].iter().take(100).all(|&b| b == 0xa3));
assert_eq!(
r.scan().anomalies(),
[ReadError::NotCleanlyUnmounted.anomaly()],
);
}
#[test]
fn reader_never_panics_on_a_mangled_log() {
let (bytes, jsb) = needing_recovery();
let bs = 4096;
fn drive(bytes: &[u8]) {
for policy in [ReadPolicy::Strict, ReadPolicy::Lenient] {
if let Ok(mut r) = Reader::open_with(
std::io::Cursor::new(bytes),
&OpenOptions::new().policy(policy),
) {
let _ = r.walk();
let _ = r.scan();
for block in [0, 1, 3000, 3001, 3002] {
let _ = r.read_block(block);
}
}
}
}
drive(&bytes);
let mut flip = bytes.clone();
let mut i = jsb * bs;
while i < (jsb + 9) * bs {
let orig = flip[i];
let header = i % bs < 64;
let ways: &[u8] = if header { &[0xff, 0x01, 0x80] } else { &[0xff] };
for &x in ways {
flip[i] = orig ^ x;
drive(&flip);
}
flip[i] = orig;
i += if header { 1 } else { 251 };
}
for n in 0..9 {
drive(&bytes[..(jsb + n) * bs + 7]);
}
}
#[test]
fn reader_never_panics_on_mangled_images() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), m(0o755))
.file(b"/etc/hostname".to_vec(), b"ferrosys\n".to_vec(), m(0o644))
.file(b"/big".to_vec(), vec![0x42; 40_000], m(0o600));
let image = format(src, 64 * MIB, opts()).unwrap().into_bytes();
fn drive(bytes: &[u8]) {
if let Ok(mut r) = Reader::open(std::io::Cursor::new(bytes)) {
let _ = r.walk();
let _ = r.verify_checksums();
let _ = r.scan();
}
if let Ok(mut r) = Reader::open_with(
std::io::Cursor::new(bytes),
&OpenOptions::new().base(512).policy(ReadPolicy::Lenient),
) {
let _ = r.scan();
}
}
drive(&image);
for (off, fill) in [
(0x00usize, 0xffu8), (0x14, 0xff), (0x20, 0x00), (0x28, 0x00), ] {
let mut mangled = image.clone();
mangled[1024 + off..1024 + off + 4].fill(fill);
drive(&mangled);
}
for len in [0usize, 1, 512, 1023, 1024, 1025, 2048, 4096, 8192, 65_536] {
drive(&image[..len.min(image.len())]);
}
let mut flip = image.clone();
let span = flip.len().min(64 * 1024);
let mut i = 0usize;
while i < span {
let orig = flip[i];
flip[i] ^= 0xff;
drive(&flip);
flip[i] = orig;
i += 251; }
drive(&vec![0x00u8; 4096 * 8]);
drive(&vec![0xffu8; 4096 * 8]);
let ramp: Vec<u8> = (0..8192u32).map(|k| (k % 256) as u8).collect();
drive(&ramp);
}
#[test]
fn walk_bounds_a_directory_cycle() {
let time = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, time);
let src = TreeBuilder::new()
.directory(b"/a".to_vec(), m(0o755))
.directory(b"/a/b".to_vec(), m(0o755));
let mut bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let (block_off, block_size) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let root = r.inode(2).unwrap();
let a_ino = r
.read_dir(&root)
.unwrap()
.into_iter()
.find(|e| e.name == b"a")
.unwrap()
.inode;
let a_inode = r.inode(a_ino).unwrap();
let bs = 1024usize << r.superblock().log_block_size;
let start = r.extent_leaves(&a_inode).unwrap()[0].start;
(start as usize * bs, bs)
};
let mut off = block_off;
let end = block_off + block_size;
loop {
let rec_len = u16::from_le_bytes([bytes[off + 4], bytes[off + 5]]) as usize;
assert!(
rec_len >= 8 && off + rec_len <= end,
"walked a valid dir block"
);
let name_len = bytes[off + 6] as usize;
if name_len == 1 && bytes[off + 8] == b'b' {
bytes[off..off + 4].copy_from_slice(&2u32.to_le_bytes());
break;
}
off += rec_len;
}
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert!(matches!(
r.walk(),
Err(ReadError::RepeatedDirectory { inode: 2 })
));
let mut r = Reader::open_with(
std::io::Cursor::new(&bytes),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
let tree = r.walk().unwrap();
let paths: Vec<&[u8]> = tree.iter().map(|e| e.path.as_slice()).collect();
assert!(paths.contains(&b"/a".as_slice()));
assert!(paths.contains(&b"/a/b".as_slice()));
assert_eq!(
paths.iter().filter(|p| **p == b"/a").count(),
1,
"the cycle did not multiply entries"
);
}
#[test]
fn the_walk_names_the_inode_each_path_points_at() {
let time = Timestamp::from_secs(1_700_000_000);
let m = Metadata::new(0o644, time);
let src = TreeBuilder::new()
.file(b"/original".to_vec(), b"shared".to_vec(), m)
.hardlink(b"/link".to_vec(), b"/original".to_vec(), m)
.file(b"/twin".to_vec(), b"shared".to_vec(), m);
let image = format(src, 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let by_path: std::collections::BTreeMap<Vec<u8>, u32> = r
.walk()
.unwrap()
.into_iter()
.map(|e| (e.path, e.number))
.collect();
assert_eq!(
by_path[&b"/link".to_vec()],
by_path[&b"/original".to_vec()],
"a hard link is the same inode under a second name"
);
assert_ne!(
by_path[&b"/twin".to_vec()],
by_path[&b"/original".to_vec()],
"identical contents are not the same file"
);
let entry = r
.walk()
.unwrap()
.into_iter()
.find(|e| e.path == b"/original")
.expect("the file is in the tree");
assert_eq!(r.inode(entry.number).unwrap(), entry.inode);
assert_eq!(entry.inode.links_count, 2, "the link is counted");
}
#[test]
fn walk_descends_a_tree_nested_past_any_recursion_cap() {
let time = Timestamp::from_secs(1_700_000_000);
let depth = 200usize;
let mut src = TreeBuilder::new();
let mut path = Vec::new();
for i in 0..depth {
path.extend_from_slice(format!("/d{i:03}").as_bytes());
src = src.directory(path.clone(), Metadata::new(0o755, time));
}
let mut leaf = path.clone();
leaf.extend_from_slice(b"/leaf");
src = src.file(leaf.clone(), b"deep\n".to_vec(), Metadata::new(0o644, time));
let bytes = format(src, 64 * MIB, opts()).unwrap().into_bytes();
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let paths: Vec<Vec<u8>> = r
.walk()
.expect("a deep tree walks in full")
.into_iter()
.map(|e| e.path)
.collect();
assert!(
paths.contains(&leaf),
"the entry {depth} levels down was not reached"
);
let in_chain = paths.iter().filter(|p| p.starts_with(b"/d000")).count();
assert_eq!(
in_chain,
depth + 1,
"every directory in the chain and the leaf appears exactly once"
);
for i in 0..depth {
let mut prefix = Vec::new();
for j in 0..=i {
prefix.extend_from_slice(format!("/d{j:03}").as_bytes());
}
assert!(
paths.contains(&prefix),
"level {i} is missing from the walk"
);
}
}
fn merged_usr() -> TreeBuilder {
let t = Timestamp::from_secs(1_700_000_000);
let m = |mode| Metadata::new(mode, t);
TreeBuilder::new()
.directory(b"/usr".to_vec(), m(0o755))
.directory(b"/usr/lib".to_vec(), m(0o755))
.directory(b"/usr/lib/modules".to_vec(), m(0o755))
.file(
b"/usr/lib/modules/vmlinuz".to_vec(),
b"not really a kernel".to_vec(),
m(0o644),
)
.directory(b"/etc".to_vec(), m(0o755))
.file(
b"/etc/fstab".to_vec(),
b"/ ext4 defaults\n".to_vec(),
m(0o644),
)
.symlink(b"/lib".to_vec(), b"usr/lib".to_vec(), m(0o777))
.symlink(
b"/absolute".to_vec(),
b"/usr/lib/modules".to_vec(),
m(0o777),
)
.symlink(b"/usr/lib64".to_vec(), b"../lib".to_vec(), m(0o777))
.symlink(b"/loop_a".to_vec(), b"loop_b".to_vec(), m(0o777))
.symlink(b"/loop_b".to_vec(), b"loop_a".to_vec(), m(0o777))
.symlink(b"/dangling".to_vec(), b"nowhere".to_vec(), m(0o777))
}
#[test]
fn lookup_follows_a_symlink_into_merged_usr() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (through_link, _) = r.lookup(b"/lib/modules").expect("/lib/modules resolves");
let (direct, _) = r.lookup(b"/usr/lib/modules").expect("/usr/lib/modules");
assert_eq!(through_link, direct, "the link reaches the same inode");
let (_, inode) = r.lookup(b"/lib/modules/vmlinuz").unwrap();
assert_eq!(r.read_data(&inode).unwrap(), b"not really a kernel");
let (abs, _) = r.lookup(b"/absolute").expect("/absolute resolves");
assert_eq!(abs, direct);
assert_eq!(r.lookup(b"lib/modules").unwrap().0, direct);
assert_eq!(r.lookup(b"//lib/./modules/").unwrap().0, direct);
assert_eq!(r.lookup(b"/").unwrap().0, 2);
}
#[test]
fn a_parent_component_ascends_whether_a_caller_wrote_it_or_a_link_stored_it() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (direct, _) = r.lookup(b"/usr/lib/modules").expect("/usr/lib/modules");
for path in [
&b"/usr/lib/../lib/modules"[..],
b"/etc/../usr/lib/modules",
b"/usr/lib64/modules",
b"/lib/modules/../modules",
] {
assert_eq!(
r.lookup(path).map(|(number, _)| number),
Ok(direct),
"{}",
String::from_utf8_lossy(path)
);
}
for path in [&b"/.."[..], b"/../..", b"..", b"/usr/lib/../../../.."] {
assert_eq!(
r.lookup(path).map(|(number, _)| number),
Ok(ROOT_INO),
"{}",
String::from_utf8_lossy(path)
);
}
assert_eq!(r.lookup(b"/../etc/fstab").map(|(n, _)| n), {
r.lookup(b"/etc/fstab").map(|(n, _)| n)
});
assert!(matches!(
r.lookup(b"/etc/fstab/.."),
Err(ReadError::NotADirectory { .. })
));
}
#[test]
fn lookup_no_follow_stops_at_the_link() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
let (_, link) = r.lookup_no_follow(b"/lib").expect("/lib as a link");
assert_eq!(link.mode & 0o170000, 0o120000, "it is a symlink");
assert_eq!(r.read_symlink(&link).unwrap(), b"usr/lib");
let (_, dir) = r.lookup(b"/lib").expect("/lib followed");
assert_eq!(dir.mode & 0o170000, 0o040000, "it is a directory");
assert_eq!(
r.lookup_no_follow(b"/lib/modules").unwrap().0,
r.lookup(b"/usr/lib/modules").unwrap().0
);
}
#[test]
fn lookup_bounds_a_symlink_cycle_and_names_what_is_missing() {
let image = format(merged_usr(), 64 * MIB, opts()).unwrap();
let mut r = Reader::open(std::io::Cursor::new(image.as_bytes())).unwrap();
assert!(matches!(
r.lookup(b"/loop_a"),
Err(ReadError::SymlinkLoop { .. })
));
assert!(matches!(
r.lookup(b"/dangling"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/nope"),
Err(ReadError::NotFound { .. })
));
assert!(matches!(
r.lookup(b"/etc/fstab/deeper"),
Err(ReadError::NotADirectory { .. })
));
assert!(r.lookup_no_follow(b"/loop_a").is_ok());
}
#[test]
fn a_reserved_inode_without_an_extra_area_verifies_on_its_low_half_alone() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
let (table, inode_size, csum) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let table = r.group_descriptor(0).unwrap().inode_table as usize;
let csum = r.checksummer();
(table, r.superblock().inode_size as usize, csum)
};
let off = table * 4096;
bytes[off + 0x80..off + inode_size].fill(0);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, 0);
let c = recipe::inode(&csum, 1, 0, &bytes[off..off + inode_size], false);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, c as u16);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
assert_eq!(
r.inode(1).unwrap().extra_isize,
0,
"the inode declares no extra area"
);
let report = r.scan();
assert!(
report.is_clean(),
"an inode storing only its low checksum half was rejected: {:?}",
report.anomalies()
);
r.verify_checksums()
.expect("and the strict verifier accepts it too");
}
#[test]
fn a_field_this_crate_does_not_model_does_not_break_the_inode_checksum() {
let image = format(TreeBuilder::new(), 64 * MIB, opts()).unwrap();
let mut bytes = image.into_bytes();
let (table, inode_size, csum) = {
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let table = r.group_descriptor(0).unwrap().inode_table as usize;
let csum = r.checksummer();
(table, r.superblock().inode_size as usize, csum)
};
let off = table * 4096 + inode_size;
crate::ondisk::put_u32(&mut bytes[off..], 0x24, 0xdead_beef); put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, 0);
put_u16(&mut bytes[off..], Inode::CHECKSUM_HI_OFFSET, 0);
let c = recipe::inode(&csum, 2, 0, &bytes[off..off + inode_size], true);
put_u16(&mut bytes[off..], Inode::CHECKSUM_LO_OFFSET, c as u16);
put_u16(
&mut bytes[off..],
Inode::CHECKSUM_HI_OFFSET,
(c >> 16) as u16,
);
let mut r = Reader::open(std::io::Cursor::new(&bytes)).unwrap();
let report = r.scan();
assert!(
report.is_clean(),
"an inode carrying a field this crate does not model was rejected: {:?}",
report.anomalies()
);
}
use crate::io::Counting;
fn read_cost_image() -> Vec<u8> {
let time = Timestamp::from_secs(1_700_000_000);
let mut tree = TreeBuilder::new();
for d in 0..8u32 {
tree = tree.directory(format!("/d{d}").into_bytes(), Metadata::new(0o755, time));
for s in 0..3u32 {
tree = tree.directory(
format!("/d{d}/s{s}").into_bytes(),
Metadata::new(0o755, time),
);
for f in 0..20u32 {
let len = ((d * 61 + s * 17 + f * 389) % 20_000) as usize;
let byte = (d + s + f) as u8;
tree = tree.file(
format!("/d{d}/s{s}/f{f}").into_bytes(),
vec![byte; len],
Metadata::new(0o644, time),
);
}
}
}
let long = |len: usize| (0..len).map(|i| (i / 4096) as u8).collect::<Vec<u8>>();
tree = tree
.file(
b"/long1".to_vec(),
long((1 << 20) + 5),
Metadata::new(0o644, time),
)
.file(
b"/long2".to_vec(),
long(3 << 20),
Metadata::new(0o644, time),
);
format(tree, 64 * MIB, opts()).unwrap().into_bytes()
}
#[test]
fn a_walk_reads_no_byte_twice() {
let (source, reads) = Counting::new(read_cost_image());
let mut r = Reader::open(source).unwrap();
reads.borrow_mut().clear();
let entries = r.walk().unwrap();
assert!(
entries.len() > 500,
"the walk reached {} entries",
entries.len()
);
let mut spans: Vec<(u64, u64)> = reads
.borrow()
.iter()
.map(|&(at, len)| (at, at + len as u64))
.collect();
spans.sort_unstable();
for pair in spans.windows(2) {
assert!(
pair[0].1 <= pair[1].0,
"the walk read {:?} and then {:?} again",
pair[0],
pair[1]
);
}
assert!(
spans.len() * 4 < entries.len(),
"{} reads for {} entries",
spans.len(),
entries.len()
);
}
#[test]
fn a_larger_table_cache_never_asks_for_more() {
let bytes = read_cost_image();
let mut counts = Vec::new();
for capacity in [0usize, 1, 2, 4, 8, 16, 64] {
let (source, reads) = Counting::new(bytes.clone());
let mut r = Reader::open(source).unwrap().with_table_capacity(capacity);
reads.borrow_mut().clear();
let entries = r.walk().unwrap();
for entry in &entries {
r.lookup(&entry.path).unwrap();
}
counts.push((capacity, reads.borrow().len()));
}
for pair in counts.windows(2) {
assert!(pair[1].1 <= pair[0].1, "{counts:?}");
}
let (none, held) = (counts[0].1, counts[counts.len() - 1].1);
assert!(
held * 2 < none,
"holding the tables cut {none} reads only to {held}"
);
}
#[test]
fn a_file_is_read_a_run_at_a_time() {
let (source, reads) = Counting::new(read_cost_image());
let mut r = Reader::open(source).unwrap();
let max = r.max_run_blocks();
let mut files = 0;
for entry in r.walk().unwrap() {
if entry.inode.mode & 0o170000 != 0o100000 || entry.inode.size == 0 {
continue;
}
let blocks = usize::try_from(entry.inode.size.div_ceil(r.block_size as u64)).unwrap();
let map = r.map_window(&entry.inode, 0, blocks).unwrap();
let expected = runs(&map, max).iter().filter(|run| run.phys != 0).count();
reads.borrow_mut().clear();
let mut sink = Vec::new();
r.read_data_to(&entry.inode, &mut sink).unwrap();
assert_eq!(
reads.borrow().len(),
expected,
"{}: {} bytes",
String::from_utf8_lossy(&entry.path),
entry.inode.size
);
files += 1;
}
assert!(files > 400, "{files} files read");
let (_, long) = r.lookup(b"/long2").unwrap();
reads.borrow_mut().clear();
let mut buf = vec![0u8; 1 << 20];
let filled = r.read_into(&long, 4096 * 3 + 7, &mut buf).unwrap();
assert_eq!(filled, 1 << 20);
assert!(reads.borrow().len() <= 5, "{:?}", reads.borrow());
let whole = r.read_data(&long).unwrap();
assert_eq!(&buf[..], &whole[4096 * 3 + 7..4096 * 3 + 7 + (1 << 20)]);
}
#[test]
fn runs_join_adjacent_blocks_and_nothing_else() {
let map = [10, 11, 12, 0, 0, 20, 22, 23, 24, 25, 0, 30];
let got: Vec<(usize, u64, usize)> = runs(&map, 3)
.iter()
.map(|r| (r.at, r.phys, r.len))
.collect();
assert_eq!(
got,
vec![
(0, 10, 3),
(3, 0, 2),
(5, 20, 1),
(6, 22, 3),
(9, 25, 1),
(10, 0, 1),
(11, 30, 1),
]
);
assert_eq!(runs(&[5, 6], 0).len(), 2);
assert_eq!(runs(&[u64::MAX, 0], 8).len(), 2);
assert!(runs(&[], 8).is_empty());
}
#[test]
fn a_source_cut_short_fails_where_a_block_at_a_time_read_does() {
let bytes = read_cost_image();
let mut r = Reader::open(std::io::Cursor::new(bytes.clone())).unwrap();
let (_, long) = r.lookup(b"/long2").unwrap();
let map = r.map_window(&long, 0, 8).unwrap();
let bs = r.block_size;
let cut = usize::try_from(map[5]).unwrap() * bs;
let mut short = Reader::open(std::io::Cursor::new(bytes[..cut].to_vec())).unwrap();
let mut sink = Vec::new();
let err = short.read_data_to(&long, &mut sink).unwrap_err();
assert!(
matches!(err, ReadError::OutOfRange { what: "block", index } if index == map[5]),
"{err:?}"
);
assert_eq!(
sink.len(),
5 * bs,
"the five blocks before the cut were written"
);
assert_eq!(sink, r.read_data(&long).unwrap()[..5 * bs]);
let last = r.walk().unwrap().iter().map(|e| e.number).max().unwrap();
let group = (last - 1) / r.sb.inodes_per_group;
let index = u64::from((last - 1) % r.sb.inodes_per_group);
let table = r.group_descriptor(group).unwrap().inode_table;
let isize = u64::from(r.sb.inode_size);
let end = usize::try_from(table * bs as u64 + (index + 1) * isize).unwrap();
assert_ne!(end % bs, 0, "the cut falls inside a table block");
let mut short = Reader::open_with(
std::io::Cursor::new(bytes[..end].to_vec()),
&OpenOptions::new().policy(ReadPolicy::Lenient),
)
.unwrap();
assert_eq!(short.inode(last).unwrap(), r.inode(last).unwrap());
}
}