docs: sync with code (topologies, mount scheme, CLI flags, UEFI/BIOS, fstab) and fix relative src links in docs/ to ../src/
This commit is contained in:
169
docs/API.md
169
docs/API.md
@@ -8,40 +8,40 @@ Conventions
|
||||
- External tooling calls are mediated via utility wrappers.
|
||||
|
||||
Module index
|
||||
- [src/main.rs](src/main.rs)
|
||||
- [src/lib.rs](src/lib.rs)
|
||||
- [src/errors.rs](src/errors.rs)
|
||||
- [src/cli/args.rs](src/cli/args.rs)
|
||||
- [src/logging/mod.rs](src/logging/mod.rs)
|
||||
- [src/types.rs](src/types.rs)
|
||||
- [src/config/loader.rs](src/config/loader.rs)
|
||||
- [src/device/discovery.rs](src/device/discovery.rs)
|
||||
- [src/partition/plan.rs](src/partition/plan.rs)
|
||||
- [src/fs/plan.rs](src/fs/plan.rs)
|
||||
- [src/mount/ops.rs](src/mount/ops.rs)
|
||||
- [src/report/state.rs](src/report/state.rs)
|
||||
- [src/orchestrator/run.rs](src/orchestrator/run.rs)
|
||||
- [src/idempotency/mod.rs](src/idempotency/mod.rs)
|
||||
- [src/util/mod.rs](src/util/mod.rs)
|
||||
- [src/main.rs](../src/main.rs)
|
||||
- [src/lib.rs](../src/lib.rs)
|
||||
- [src/errors.rs](../src/errors.rs)
|
||||
- [src/cli/args.rs](../src/cli/args.rs)
|
||||
- [src/logging/mod.rs](../src/logging/mod.rs)
|
||||
- [src/types.rs](../src/types.rs)
|
||||
- [src/config/loader.rs](../src/config/loader.rs)
|
||||
- [src/device/discovery.rs](../src/device/discovery.rs)
|
||||
- [src/partition/plan.rs](../src/partition/plan.rs)
|
||||
- [src/fs/plan.rs](../src/fs/plan.rs)
|
||||
- [src/mount/ops.rs](../src/mount/ops.rs)
|
||||
- [src/report/state.rs](../src/report/state.rs)
|
||||
- [src/orchestrator/run.rs](../src/orchestrator/run.rs)
|
||||
- [src/idempotency/mod.rs](../src/idempotency/mod.rs)
|
||||
- [src/util/mod.rs](../src/util/mod.rs)
|
||||
|
||||
Common errors and result
|
||||
- [enum Error](src/errors.rs:1)
|
||||
- [enum Error](../src/errors.rs:1)
|
||||
- Top-level error type covering parse/validation errors, device discovery errors, partitioning failures, filesystem mkfs errors, mount errors, report write errors, and external tool invocation failures with stderr capture.
|
||||
- [type Result<T> = std::result::Result<T, Error>](src/errors.rs:1)
|
||||
- [type Result<T> = std::result::Result<T, Error>](../src/errors.rs:1)
|
||||
- Shared result alias across modules.
|
||||
|
||||
Crate root
|
||||
- [src/lib.rs](src/lib.rs)
|
||||
- [src/lib.rs](../src/lib.rs)
|
||||
- Exposes crate version constants, the prelude, and re-exports common types for consumers of the library (tests/integration). No heavy logic.
|
||||
|
||||
Entrypoint
|
||||
- [fn main()](src/main.rs:1)
|
||||
- [fn main()](../src/main.rs:1)
|
||||
- Initializes logging based on CLI defaults, parses CLI flags and kernel cmdline, loads and validates configuration, and invokes the orchestrator run sequence. Avoids stdout; logs via tracing only.
|
||||
|
||||
Orchestrator
|
||||
- [struct Context](src/orchestrator/run.rs:1)
|
||||
- [struct Context](../src/orchestrator/run.rs:1)
|
||||
- Aggregates resolved configuration, logging options, and environment flags suited for initramfs execution.
|
||||
- [fn run(ctx: &Context) -> Result<()>](src/orchestrator/run.rs:1)
|
||||
- [fn run(ctx: &Context) -> Result<()>](../src/orchestrator/run.rs:1)
|
||||
- High-level one-shot flow:
|
||||
- Idempotency detection
|
||||
- Device discovery
|
||||
@@ -52,131 +52,141 @@ Orchestrator
|
||||
- Aborts the entire run on any validation or execution failure. Returns Ok on successful no-op if already provisioned.
|
||||
|
||||
CLI
|
||||
- [struct Cli](src/cli/args.rs:1)
|
||||
- [struct Cli](../src/cli/args.rs:1)
|
||||
- Mirrors kernel cmdline semantics with flags:
|
||||
- --config PATH
|
||||
- --log-level LEVEL
|
||||
- --log-to-file
|
||||
- --fstab
|
||||
- --show
|
||||
- --report PATH
|
||||
- --apply
|
||||
- --force (present, returns unimplemented error)
|
||||
- [fn from_args() -> Cli](src/cli/args.rs:1)
|
||||
- [fn from_args() -> Cli](../src/cli/args.rs:1)
|
||||
- Parses argv without side effects; suitable for initramfs.
|
||||
|
||||
Logging
|
||||
- [struct LogOptions](src/logging/mod.rs:1)
|
||||
- [struct LogOptions](../src/logging/mod.rs:1)
|
||||
- Holds level and optional file target (/run/zosstorage/zosstorage.log).
|
||||
- [fn init_logging(opts: &LogOptions) -> Result<()>](src/logging/mod.rs:1)
|
||||
- [fn init_logging(opts: &LogOptions) -> Result<()>](../src/logging/mod.rs:1)
|
||||
- Configures tracing-subscriber for stderr by default and optional file layer when enabled. Must be idempotent.
|
||||
|
||||
Configuration types
|
||||
- [struct Config](src/types.rs:1)
|
||||
- [struct Config](../src/types.rs:1)
|
||||
- The validated configuration used by the orchestrator, containing logging, device selection rules, topology, partitioning, filesystem options, mount scheme, and report path.
|
||||
- [enum Topology](src/types.rs:1)
|
||||
- Values: btrfs_single, bcachefs_single, dual_independent, bcachefs_2copy, ssd_hdd_bcachefs, btrfs_raid1 (opt-in).
|
||||
- [struct DeviceSelection](src/types.rs:1)
|
||||
- [enum Topology](../src/types.rs:1)
|
||||
- Values: btrfs_single, bcachefs_single, dual_independent, bcachefs2_copy, ssd_hdd_bcachefs, btrfs_raid1 (opt-in).
|
||||
- [struct DeviceSelection](../src/types.rs:1)
|
||||
- Include and exclude regex patterns, minimum size, removable policy.
|
||||
- [struct Partitioning](src/types.rs:1)
|
||||
- [struct Partitioning](../src/types.rs:1)
|
||||
- Alignment, emptiness requirement, bios_boot, esp, data, cache GPT names and sizes where applicable.
|
||||
- [struct BtrfsOptions](src/types.rs:1)
|
||||
- [struct BtrfsOptions](../src/types.rs:1)
|
||||
- Compression string and raid profile (none or raid1).
|
||||
- [struct BcachefsOptions](src/types.rs:1)
|
||||
- [struct BcachefsOptions](../src/types.rs:1)
|
||||
- Cache mode (promote or writeback), compression, checksum.
|
||||
- [struct VfatOptions](src/types.rs:1)
|
||||
- [struct VfatOptions](../src/types.rs:1)
|
||||
- Reserved for ESP mkfs options; includes label ZOSBOOT.
|
||||
- [struct FsOptions](src/types.rs:1)
|
||||
- [struct FsOptions](../src/types.rs:1)
|
||||
- Aggregates BtrfsOptions, BcachefsOptions, VfatOptions and shared defaults such as ZOSDATA label.
|
||||
- [enum MountSchemeKind](src/types.rs:1)
|
||||
- [enum MountSchemeKind](../src/types.rs:1)
|
||||
- Values: per_uuid, custom (future).
|
||||
- [struct MountScheme](src/types.rs:1)
|
||||
- [struct MountScheme](../src/types.rs:1)
|
||||
- Base directory (/var/cache), scheme kind, fstab enabled flag.
|
||||
- [struct ReportOptions](src/types.rs:1)
|
||||
- [struct ReportOptions](../src/types.rs:1)
|
||||
- Output path (/run/zosstorage/state.json).
|
||||
|
||||
Configuration IO
|
||||
- [fn load_and_merge(cli: &Cli) -> Result<Config>](src/config/loader.rs:1)
|
||||
- [fn load_and_merge(cli: &Cli) -> Result<Config>](../src/config/loader.rs:1)
|
||||
- Loads built-in defaults, optionally merges on-disk config, overlays CLI flags, and finally overlays kernel cmdline via zosstorage.config=. Validates the YAML against types and constraints.
|
||||
- [fn validate(cfg: &Config) -> Result<()>](src/config/loader.rs:1)
|
||||
- [fn validate(cfg: &Config) -> Result<()>](../src/config/loader.rs:1)
|
||||
- Ensures structural and semantic validity (e.g., disk selection rules not empty, sizes non-zero, supported topology combinations).
|
||||
|
||||
Device discovery
|
||||
- [struct Disk](src/device/discovery.rs:1)
|
||||
- [struct Disk](../src/device/discovery.rs:1)
|
||||
- Represents an eligible block device with path, size, rotational flag, and identifiers (serial, model if available).
|
||||
- [struct DeviceFilter](src/device/discovery.rs:1)
|
||||
- [struct DeviceFilter](../src/device/discovery.rs:1)
|
||||
- Derived from DeviceSelection; compiled regexes and size thresholds for efficient filtering.
|
||||
- [trait DeviceProvider](src/device/discovery.rs:1)
|
||||
- [trait DeviceProvider](../src/device/discovery.rs:1)
|
||||
- Abstraction for listing /dev and probing properties, enabling test doubles.
|
||||
- [fn discover(filter: &DeviceFilter) -> Result<Vec<Disk>>](src/device/discovery.rs:1)
|
||||
- [fn discover(filter: &DeviceFilter) -> Result<Vec<Disk>>](../src/device/discovery.rs:1)
|
||||
- Returns eligible disks or a well-defined error if none are found.
|
||||
|
||||
Partitioning
|
||||
- [enum PartRole](src/partition/plan.rs:1)
|
||||
- [enum PartRole](../src/partition/plan.rs:1)
|
||||
- Roles: BiosBoot, Esp, Data, Cache.
|
||||
- [struct PartitionSpec](src/partition/plan.rs:1)
|
||||
- [struct PartitionSpec](../src/partition/plan.rs:1)
|
||||
- Declarative spec for a single partition: role, optional size_mib, gpt_name (zosboot, zosdata, zoscache), and reserved filesystem label when role is Esp (ZOSBOOT).
|
||||
- [struct DiskPlan](src/partition/plan.rs:1)
|
||||
- [struct DiskPlan](../src/partition/plan.rs:1)
|
||||
- The planned set of PartitionSpec instances for a single Disk in the chosen topology.
|
||||
- [struct PartitionPlan](src/partition/plan.rs:1)
|
||||
- [struct PartitionPlan](../src/partition/plan.rs:1)
|
||||
- Combined plan across all target disks, including alignment rules and safety checks.
|
||||
- [struct PartitionResult](src/partition/plan.rs:1)
|
||||
- [struct PartitionResult](../src/partition/plan.rs:1)
|
||||
- Result of applying a DiskPlan: device path of each created partition, role, partition GUID, and gpt_name.
|
||||
- [fn plan_partitions(disks: &[Disk], cfg: &Config) -> Result<PartitionPlan>](src/partition/plan.rs:1)
|
||||
- [fn plan_partitions(disks: &[Disk], cfg: &Config) -> Result<PartitionPlan>](../src/partition/plan.rs:1)
|
||||
- Produces a GPT-only plan with 1 MiB alignment, bios boot first (1 MiB), ESP 512 MiB, data remainder, and zoscache on SSD for ssd_hdd_bcachefs.
|
||||
- [fn apply_partitions(plan: &PartitionPlan) -> Result<Vec<PartitionResult>>](src/partition/plan.rs:1)
|
||||
- [fn apply_partitions(plan: &PartitionPlan) -> Result<Vec<PartitionResult>>](../src/partition/plan.rs:1)
|
||||
- Executes the plan via sgdisk and related utilities. Aborts if target disks are not empty or if signatures are detected.
|
||||
|
||||
Filesystems
|
||||
- [enum FsKind](src/fs/plan.rs:1)
|
||||
- [enum FsKind](../src/fs/plan.rs:1)
|
||||
- Values: Vfat, Btrfs, Bcachefs.
|
||||
- [struct FsSpec](src/fs/plan.rs:1)
|
||||
- [struct FsSpec](../src/fs/plan.rs:1)
|
||||
- Maps PartitionResult to desired filesystem kind and label (ZOSBOOT for ESP; ZOSDATA for all data filesystems including bcachefs).
|
||||
- [struct FsPlan](src/fs/plan.rs:1)
|
||||
- [struct FsPlan](../src/fs/plan.rs:1)
|
||||
- Plan of mkfs operations across all partitions and devices given the topology.
|
||||
- [struct FsResult](src/fs/plan.rs:1)
|
||||
- [struct FsResult](../src/fs/plan.rs:1)
|
||||
- Output of mkfs: device path(s), fs uuid, label, and kind.
|
||||
- [fn plan_filesystems(disks: &[Disk], parts: &[PartitionResult], cfg: &Config) -> Result<FsPlan>](src/fs/plan.rs:1)
|
||||
- [fn plan_filesystems(disks: &[Disk], parts: &[PartitionResult], cfg: &Config) -> Result<FsPlan>](../src/fs/plan.rs:1)
|
||||
- Determines which partitions receive vfat, btrfs, or bcachefs, and aggregates tuning options.
|
||||
- [fn make_filesystems(plan: &FsPlan) -> Result<Vec<FsResult>>](src/fs/plan.rs:1)
|
||||
- [fn make_filesystems(plan: &FsPlan, cfg: &Config) -> Result<Vec<FsResult>>](../src/fs/plan.rs:1)
|
||||
- Invokes mkfs.vfat, mkfs.btrfs, mkfs.bcachefs accordingly via utility wrappers and returns filesystem identities.
|
||||
|
||||
Mounting
|
||||
- [struct MountPlan](src/mount/ops.rs:1)
|
||||
- Derived from FsResult entries: creates target directories under /var/cache/<UUID> and the mounts required for the current boot.
|
||||
- [struct MountResult](src/mount/ops.rs:1)
|
||||
- [struct MountPlan](../src/mount/ops.rs:1)
|
||||
- Derived from FsResult entries. Plans:
|
||||
- Root mounts for all data filesystems under `/var/mounts/{UUID}` (runtime only).
|
||||
- btrfs root options: `rw,noatime,subvolid=5`
|
||||
- bcachefs root options: `rw,noatime`
|
||||
- Final subvolume/subdir mounts (from the primary data filesystem) to:
|
||||
- `/var/cache/system`, `/var/cache/etc`, `/var/cache/modules`, `/var/cache/vm-meta`
|
||||
- [struct MountResult](../src/mount/ops.rs:1)
|
||||
- Actual mount operations performed (source, target, fstype, options).
|
||||
- [fn plan_mounts(fs_results: &[FsResult], cfg: &Config) -> Result<MountPlan>](src/mount/ops.rs:1)
|
||||
- Translates filesystem identities to mount targets and options.
|
||||
- [fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>>](src/mount/ops.rs:1)
|
||||
- Performs mounts using syscalls (nix crate) with minimal dependencies. Ensures directories exist.
|
||||
- [fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()>](src/mount/ops.rs:1)
|
||||
- When enabled, generates /etc/fstab entries in deterministic order. Disabled by default.
|
||||
- [fn plan_mounts(fs_results: &[FsResult], cfg: &Config) -> Result<MountPlan>](../src/mount/ops.rs:1)
|
||||
- Translates filesystem identities to mount targets and options, including `subvol=` for btrfs and `X-mount.subdir=` for bcachefs.
|
||||
- [fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>>](../src/mount/ops.rs:1)
|
||||
- Performs mounts using syscalls (nix crate). Ensures directories exist and creates subvolumes/subdirs if missing.
|
||||
- [fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()>](../src/mount/ops.rs:1)
|
||||
- When enabled, writes only the four subvolume/subdir mount entries to `/etc/fstab` in deterministic order using `UUID=` sources. Root mounts under `/var/mounts` are excluded.
|
||||
|
||||
Reporting
|
||||
- [const REPORT_VERSION: &str](src/report/state.rs:1)
|
||||
- [const REPORT_VERSION: &str](../src/report/state.rs:1)
|
||||
- Version string for the JSON payload schema.
|
||||
- [struct StateReport](src/report/state.rs:1)
|
||||
- [struct StateReport](../src/report/state.rs:1)
|
||||
- Machine-readable state describing discovered disks, created partitions, filesystems, labels, mountpoints, status, and timestamp.
|
||||
- [fn build_report(disks: &[Disk], parts: &[PartitionResult], fs: &[FsResult], mounts: &[MountResult], status: &str) -> StateReport](src/report/state.rs:1)
|
||||
- [fn build_report(disks: &[Disk], parts: &[PartitionResult], fs: &[FsResult], mounts: &[MountResult], status: &str) -> StateReport](../src/report/state.rs:1)
|
||||
- Constructs a StateReport matching REPORT_VERSION.
|
||||
- [fn write_report(report: &StateReport) -> Result<()>](src/report/state.rs:1)
|
||||
- [fn write_report(report: &StateReport) -> Result<()>](../src/report/state.rs:1)
|
||||
- Writes JSON to /run/zosstorage/state.json (configurable).
|
||||
|
||||
Idempotency
|
||||
- [fn detect_existing_state() -> Result<Option<StateReport>>](src/idempotency/mod.rs:1)
|
||||
- [fn detect_existing_state() -> Result<Option<StateReport>>](../src/idempotency/mod.rs:1)
|
||||
- Probes for expected GPT names (zosboot, zosdata, zoscache where applicable) and filesystem labels (ZOSBOOT, ZOSDATA). If present and consistent, returns a StateReport; orchestrator exits success without changes.
|
||||
- [fn is_empty_disk(disk: &Disk) -> Result<bool>](src/idempotency/mod.rs:1)
|
||||
- [fn is_empty_disk(disk: &Disk) -> Result<bool>](../src/idempotency/mod.rs:1)
|
||||
- Determines disk emptiness: absence of partitions and known filesystem signatures.
|
||||
|
||||
Utilities
|
||||
- [struct CmdOutput](src/util/mod.rs:1)
|
||||
- [struct CmdOutput](../src/util/mod.rs:1)
|
||||
- Captures status, stdout, stderr from external tool invocations.
|
||||
- [fn which_tool(name: &str) -> Result<Option<String>>](src/util/mod.rs:1)
|
||||
- [fn which_tool(name: &str) -> Result<Option<String>>](../src/util/mod.rs:1)
|
||||
- Locates a required system utility in PATH, returning its absolute path if available.
|
||||
- [fn run_cmd(args: &[&str]) -> Result<()>](src/util/mod.rs:1)
|
||||
- [fn run_cmd(args: &[&str]) -> Result<()>](../src/util/mod.rs:1)
|
||||
- Executes a command (args[0] is binary) and returns Ok when exit status is zero; logs stderr on failure.
|
||||
- [fn run_cmd_capture(args: &[&str]) -> Result<CmdOutput>](src/util/mod.rs:1)
|
||||
- [fn run_cmd_capture(args: &[&str]) -> Result<CmdOutput>](../src/util/mod.rs:1)
|
||||
- Executes a command and returns captured output for parsing (e.g., blkid).
|
||||
- [fn udev_settle(timeout_ms: u64) -> Result<()>](src/util/mod.rs:1)
|
||||
- [fn udev_settle(timeout_ms: u64) -> Result<()>](../src/util/mod.rs:1)
|
||||
- Calls udevadm settle with a timeout when available; otherwise no-ops with a warning.
|
||||
- [fn is_efi_boot() -> bool](../src/util/mod.rs:1)
|
||||
- Detects UEFI environment by checking `/sys/firmware/efi`; used to suppress BIOS boot partition creation on UEFI systems.
|
||||
|
||||
Behavioral notes and contracts
|
||||
- Safety and idempotency:
|
||||
@@ -188,10 +198,13 @@ Behavioral notes and contracts
|
||||
- Data filesystems use label ZOSDATA regardless of backend kind.
|
||||
- Cache partitions in bcachefs topology use GPT name zoscache.
|
||||
- Topology-specific behavior:
|
||||
- single: one data filesystem (btrfs) on the sole disk.
|
||||
- dual_independent: two separate btrfs filesystems, one per disk.
|
||||
- btrfs_single: one data filesystem (btrfs) on the sole disk.
|
||||
- bcachefs_single: one data filesystem (bcachefs) on the sole disk.
|
||||
- dual_independent: independent btrfs filesystems on each eligible disk (one or more).
|
||||
- bcachefs2_copy: multi-device bcachefs across two or more data partitions with `--replicas=2` (data and metadata).
|
||||
- ssd_hdd_bcachefs: bcachefs spanning SSD (cache/promote) and HDD (backing), labeled ZOSDATA.
|
||||
- btrfs_raid1: only when explicitly requested; otherwise default to independent btrfs.
|
||||
- UEFI vs BIOS: when running under UEFI (`/sys/firmware/efi` present), the BIOS boot partition is suppressed.
|
||||
|
||||
Module dependency overview
|
||||
|
||||
|
||||
Reference in New Issue
Block a user