pi_block_device 0.1.0

Asynchronous copy-on-write block storage abstractions
Documentation
//! 文件布局初始化、恢复验证和孤儿清理。

use std::ffi::OsString;
use std::fs::{self, File, OpenOptions};
use std::io;
use std::path::{Path, PathBuf};

use super::{InitHooks, InitStage, layout};

/// 打开路径时识别出的根目录类别。
pub(crate) enum RootKind {
    /// 根路径不存在。
    Missing,
    /// 根路径是严格空目录。
    Empty,
    /// 根路径已有内容,需要按恢复布局处理。
    Existing,
}

/// 初始化失败时需要逆序清理的已创建路径集合。
pub(crate) struct CreatedPaths {
    /// 初始化目标根路径,用于失败时最后删除新建根目录。
    root: PathBuf,
    /// 本次初始化是否创建了根目录;已有空目录不得被删除。
    root_created: bool,
    /// 按创建顺序记录的文件与目录,cleanup 按逆序删除。
    paths: Vec<PathBuf>,
}

impl CreatedPaths {
    /// 创建初始化清理账本并记录根目录所有权。
    pub(crate) fn new(root: &Path, root_created: bool) -> Self {
        Self {
            root: root.to_path_buf(),
            root_created,
            paths: Vec::new(),
        }
    }

    /// 登记一个已成功创建且由本次初始化负责清理的路径。
    pub(crate) fn record(&mut self, path: PathBuf) {
        self.paths.push(path);
    }

    /// 逆序尽力删除已创建项;仅在本次创建根时删除根目录。
    pub(crate) fn cleanup(mut self) {
        while let Some(path) = self.paths.pop() {
            if path.is_dir() {
                let _ = fs::remove_dir(&path);
            } else {
                let _ = fs::remove_file(&path);
            }
        }
        if self.root_created {
            let _ = fs::remove_dir(&self.root);
        }
    }
}

/// 区分路径不存在、严格空目录和已有内容;已有非目录也归 Existing 交由布局验证。
pub(crate) fn classify_root(root: &Path) -> io::Result<RootKind> {
    if !root.exists() {
        return Ok(RootKind::Missing);
    }
    if !root.is_dir() {
        return Ok(RootKind::Existing);
    }
    if fs::read_dir(root)?.next().is_none() {
        Ok(RootKind::Empty)
    } else {
        Ok(RootKind::Existing)
    }
}

/// 只创建目标根目录本身,不递归创建父目录。
pub(crate) fn create_root(root: &Path) -> io::Result<()> {
    fs::create_dir(root)
}

/// 要求恢复根仅含各一个 data 与 log 普通目录,其他条目返回 false。
pub(crate) fn validate_root_layout(root: &Path) -> io::Result<bool> {
    let mut data_found = false;
    let mut log_found = false;
    for entry in fs::read_dir(root)? {
        let entry = entry?;
        let file_type = entry.file_type()?;
        match entry.file_name().to_str() {
            Some("data") if file_type.is_dir() && !data_found => data_found = true,
            Some("log") if file_type.is_dir() && !log_found => log_found = true,
            _ => return Ok(false),
        }
    }
    Ok(data_found && log_found)
}

/// 以 create_new 创建首个日志文件,同步文件后同步 log 目录。
pub(crate) fn create_initial_log_file<H: InitHooks>(
    root: &Path,
    created: &mut CreatedPaths,
    hooks: &H,
) -> io::Result<()> {
    let path = layout::initial_log_file(root);
    let file = OpenOptions::new()
        .write(true)
        .create_new(true)
        .open(&path)?;
    created.record(path);
    hooks.sync_file(&file, InitStage::LogFile)?;
    hooks.sync_directory(&layout::log_dir(root), InitStage::LogDirectory)
}

/// 创建 data/log 目录和 15 个空 Active 文件,并按文件、目录、根顺序同步。
pub(crate) fn create_initial_files<H: InitHooks>(
    root: &Path,
    created: &mut CreatedPaths,
    hooks: &H,
) -> io::Result<()> {
    let data = layout::data_dir(root);
    fs::create_dir(&data)?;
    created.record(data.clone());
    let log = layout::log_dir(root);
    fs::create_dir(&log)?;
    created.record(log);
    for level in 0_u8..=14 {
        let path = layout::active_file(root, level);
        let file = OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&path)?;
        created.record(path);
        hooks.sync_file(&file, InitStage::ActiveFile(level))?;
    }
    hooks.sync_directory(&data, InitStage::DataDirectory)?;
    hooks.sync_directory(root, InitStage::RootDirectory)?;
    Ok(())
}

#[cfg(unix)]
/// 在 Unix 以 `O_NOFOLLOW | O_DIRECTORY | O_NONBLOCK` 打开 `data/`,拒绝最终 symlink,并在同一句柄确认目录类型。父路径仍按路径解析,不能消除主动并发换名。
fn open_data_directory(path: &Path) -> io::Result<File> {
    use std::os::unix::fs::OpenOptionsExt;

    let file = OpenOptions::new()
        .read(true)
        .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK | libc::O_DIRECTORY)
        .open(path)
        .map_err(|error| {
            if error.raw_os_error() == Some(libc::ELOOP) {
                invalid_data("data directory is a symbolic link")
            } else {
                error
            }
        })?;
    if !file.metadata()?.is_dir() {
        return Err(invalid_data("data path is not a directory"));
    }
    Ok(file)
}

#[cfg(windows)]
/// 在 Windows 使用 `OPEN_REPARSE_POINT | BACKUP_SEMANTICS` 打开目录,并以句柄 metadata 拒绝 reparse point;父路径并发替换仍不在保证内。
fn open_data_directory(path: &Path) -> io::Result<File> {
    use std::os::windows::fs::{MetadataExt, OpenOptionsExt};

    /// FILE_ATTRIBUTE_REPARSE_POINT 的内部固定值。
    const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
    /// FILE_FLAG_BACKUP_SEMANTICS 的内部固定值。
    const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
    /// FILE_FLAG_OPEN_REPARSE_POINT 的内部固定值。
    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;

    let file = OpenOptions::new()
        .read(true)
        .custom_flags(FILE_FLAG_BACKUP_SEMANTICS | FILE_FLAG_OPEN_REPARSE_POINT)
        .open(path)?;
    let metadata = file.metadata()?;
    if metadata.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
        return Err(invalid_data("data directory is a reparse point"));
    }
    if !metadata.is_dir() {
        return Err(invalid_data("data path is not a directory"));
    }
    Ok(file)
}

#[cfg(not(any(unix, windows)))]
/// 在非 Unix/Windows 平台先用 `symlink_metadata` 做静态类型预检,再按路径打开目录;预检与打开之间存在替换竞态。
fn open_data_directory(path: &Path) -> io::Result<File> {
    let metadata = fs::symlink_metadata(path)?;
    if metadata.file_type().is_symlink() {
        return Err(invalid_data("data directory is a symbolic link"));
    }
    if !metadata.is_dir() {
        return Err(invalid_data("data path is not a directory"));
    }
    File::open(path)
}

#[cfg(unix)]
/// 在 Unix 对已打开目录句柄执行 `sync_all`,任何错误都向上传播。
fn sync_open_directory(directory: &File) -> io::Result<()> {
    directory.sync_all()
}

#[cfg(windows)]
/// 在 Windows 尝试同步目录句柄;`PermissionDenied`/`InvalidInput` 视为平台不支持并 best effort 成功,其他错误传播。
fn sync_open_directory(directory: &File) -> io::Result<()> {
    match directory.sync_all() {
        Ok(()) => Ok(()),
        Err(error)
            if matches!(
                error.kind(),
                io::ErrorKind::PermissionDenied | io::ErrorKind::InvalidInput
            ) =>
        {
            Ok(())
        }
        Err(error) => Err(error),
    }
}

#[cfg(not(any(unix, windows)))]
/// 在其他平台直接对已打开目录句柄执行 `sync_all`;支持程度由平台标准库决定。
fn sync_open_directory(directory: &File) -> io::Result<()> {
    directory.sync_all()
}

#[cfg(unix)]
/// 在 Unix 以 `O_NOFOLLOW | O_NONBLOCK` 打开叶子,避免跟随最终 symlink 或因 FIFO 阻塞;随后调用方必须用句柄 metadata 验证 regular file。
fn open_data_file(path: &Path, write: bool) -> io::Result<File> {
    use std::os::unix::fs::OpenOptionsExt;

    let mut options = OpenOptions::new();
    options
        .read(true)
        .write(write)
        .custom_flags(libc::O_NOFOLLOW | libc::O_NONBLOCK);
    match options.open(path) {
        Ok(file) => Ok(file),
        Err(error) if error.raw_os_error() == Some(libc::ELOOP) => {
            Err(invalid_data("data path is a symbolic link"))
        }
        Err(error) => Err(error),
    }
}

#[cfg(windows)]
/// 在 Windows 以 `OPEN_REPARSE_POINT` 打开叶子并用句柄属性拒绝 reparse point;`write` 仅为 Active 截断授予写权限。
fn open_data_file(path: &Path, write: bool) -> io::Result<File> {
    use std::os::windows::fs::{MetadataExt, OpenOptionsExt};

    /// FILE_ATTRIBUTE_REPARSE_POINT 的内部固定值。
    const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x0000_0400;
    /// FILE_FLAG_OPEN_REPARSE_POINT 的内部固定值。
    const FILE_FLAG_OPEN_REPARSE_POINT: u32 = 0x0020_0000;

    let mut options = OpenOptions::new();
    options
        .read(true)
        .write(write)
        .custom_flags(FILE_FLAG_OPEN_REPARSE_POINT);
    let file = options.open(path)?;
    if file.metadata()?.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {
        return Err(invalid_data("data path is a reparse point"));
    }
    Ok(file)
}

#[cfg(not(any(unix, windows)))]
/// 在其他平台执行静态 symlink 预检后按路径打开叶子;预检和打开非原子,调用方仍需句柄类型复验。
fn open_data_file(path: &Path, write: bool) -> io::Result<File> {
    let metadata = fs::symlink_metadata(path)?;
    if metadata.file_type().is_symlink() {
        return Err(invalid_data("data path is a symbolic link"));
    }
    OpenOptions::new().read(true).write(write).open(path)
}

/// 仅用 `symlink_metadata` 对当前路径快照做类型预检,拒绝 symlink 和非 regular 文件;它不负责打开,也不消除预检后的路径替换竞态。
fn precheck_regular_path(path: &Path, message: &str) -> io::Result<()> {
    let metadata = fs::symlink_metadata(path)?;
    let file_type = metadata.file_type();
    if file_type.is_symlink() || !file_type.is_file() {
        return Err(invalid_data(message));
    }
    Ok(())
}

/// 在已打开 File 句柄上读取 metadata 并要求 regular file,消除路径 metadata 到 open 的句柄切换。
fn validate_regular_file(file: &File, message: &str) -> io::Result<fs::Metadata> {
    let metadata = file.metadata()?;
    if !metadata.is_file() {
        return Err(invalid_data(message));
    }
    Ok(metadata)
}

/// 安全验证所有 State 引用段和大块;Active 完整冗余尾部在同句柄截断并 sync_all。
pub(crate) fn validate_segment_files(root: &Path, state: &super::state::State) -> io::Result<()> {
    let data_dir = layout::data_dir(root);
    let _data_directory = open_data_directory(&data_dir)?;
    for record in state.segments.values() {
        let path = data_dir.join(format!("{:x}.{:07x}", record.level, record.version));
        precheck_regular_path(&path, "segment path is not a regular file")?;
        let write = record.state == super::state::SegmentState::Active;
        let file = open_data_file(&path, write)?;
        let metadata = validate_regular_file(&file, "segment path is not a regular file")?;
        let slot_size = super::SUPPORTED_BLOCK_SIZES[usize::from(record.level)];
        let expected = record
            .frontier
            .checked_mul(slot_size)
            .ok_or_else(|| invalid_data("segment length overflow"))?;
        let actual = metadata.len();
        match record.state {
            super::state::SegmentState::Sealed if actual != expected => {
                return Err(invalid_data("sealed segment length mismatch"));
            }
            super::state::SegmentState::Active if actual < expected || actual % slot_size != 0 => {
                return Err(invalid_data("invalid active segment length"));
            }
            super::state::SegmentState::Active if actual > expected => {
                file.set_len(expected)?;
                file.sync_all()?;
            }
            _ => {}
        }
    }
    for (&id, &logical_len) in &state.large_blocks {
        let path = data_dir.join(format!("l{id:015x}"));
        precheck_regular_path(&path, "large block path is not a regular file")?;
        let file = open_data_file(&path, false)?;
        let metadata = validate_regular_file(&file, "large block path is not a regular file")?;
        if metadata.len() != logical_len {
            return Err(invalid_data("large block file length mismatch"));
        }
    }
    Ok(())
}

/// 以 OsString 比较引用名,删除所有未引用 regular file;特殊条目失败并最终同步 data 目录。
pub(crate) fn remove_orphan_data_files(root: &Path, state: &super::state::State) -> io::Result<()> {
    let data_dir = layout::data_dir(root);
    let data_directory = open_data_directory(&data_dir)?;
    let mut referenced = std::collections::BTreeSet::<OsString>::new();
    for record in state.segments.values() {
        referenced.insert(OsString::from(format!(
            "{:x}.{:07x}",
            record.level, record.version
        )));
    }
    for id in state.large_blocks.keys() {
        referenced.insert(OsString::from(format!("l{id:015x}")));
    }
    for entry in fs::read_dir(&data_dir)? {
        let entry = entry?;
        let name = entry.file_name();
        if referenced.contains(&name) {
            continue;
        }
        let file_type = entry.file_type()?;
        if file_type.is_symlink() || !file_type.is_file() {
            return Err(invalid_data("data directory contains a non-regular entry"));
        }
        let file = open_data_file(&entry.path(), false)?;
        validate_regular_file(&file, "data directory contains a non-regular entry")?;
        fs::remove_file(entry.path())?;
    }
    sync_open_directory(&data_directory)
}

/// 构造恢复布局或文件类型不符合约束的 InvalidData。
fn invalid_data(message: &str) -> io::Error {
    io::Error::new(io::ErrorKind::InvalidData, message)
}

#[cfg(unix)]
/// Unix 按路径打开目录并要求 `sync_all` 成功;该通用辅助未使用 no-follow 目录句柄。
pub(crate) fn sync_directory(path: &Path) -> io::Result<()> {
    File::open(path)?.sync_all()
}

#[cfg(windows)]
/// Windows 尝试按路径打开并同步目录;对 `PermissionDenied`/`InvalidInput` 采用 best effort,其他错误传播。
pub(crate) fn sync_directory(path: &Path) -> io::Result<()> {
    match File::open(path).and_then(|file| file.sync_all()) {
        Ok(()) => Ok(()),
        Err(error)
            if matches!(
                error.kind(),
                io::ErrorKind::PermissionDenied | io::ErrorKind::InvalidInput
            ) =>
        {
            Ok(())
        }
        Err(error) => Err(error),
    }
}