zosstorage/docs/API.md

zosstorage Public API Skeletons

This document defines the initial public API surface for all modules. It lists traits, structs, enums, constants, and functions with responsibilities and behavioral contracts. Implementations are intentionally deferred until approval. Function bodies will be added later and guarded by todo placeholders.

Conventions

• All modules return a shared Result alias and Error enum.
• No interactive prompts; APIs are deterministic and suitable for initramfs use.
• External tooling calls are mediated via utility wrappers.

Module index

• src/main.rs
• src/lib.rs
• src/errors.rs
• src/cli/args.rs
• src/logging/mod.rs
• src/types.rs
• src/config/loader.rs
• src/device/discovery.rs
• src/partition/plan.rs
• src/fs/plan.rs
• src/mount/ops.rs
• src/report/state.rs
• src/orchestrator/run.rs
• src/idempotency/mod.rs
• src/util/mod.rs

Common errors and result

• enum Error
  • 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 = std::result::Result<T, Error>
  • Shared result alias across modules.

Crate root

• 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()
  • 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
  • Aggregates resolved configuration, logging options, and environment flags suited for initramfs execution.
• fn run(ctx: &Context) -> Result<()>
  • High-level one-shot flow:
    • Idempotency detection
    • Device discovery
    • Partition planning and application
    • Filesystem planning and creation
    • Mount planning and application
    • Report generation and write
  • Aborts the entire run on any validation or execution failure. Returns Ok on successful no-op if already provisioned.

CLI

• struct Cli
  • 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
  • Parses argv without side effects; suitable for initramfs.

Logging

• struct LogOptions
  • Holds level and optional file target (/run/zosstorage/zosstorage.log).
• fn init_logging(opts: &LogOptions) -> Result<()>
  • Configures tracing-subscriber for stderr by default and optional file layer when enabled. Must be idempotent.

Configuration types

• struct Config
  • The validated configuration used by the orchestrator, containing logging, device selection rules, topology, partitioning, filesystem options, mount scheme, and report path.
• enum Topology
  • Values: btrfs_single, bcachefs_single, dual_independent, bcachefs-2copy, ssd_hdd_bcachefs, btrfs_raid1 (opt-in).
• struct DeviceSelection
  • Include and exclude regex patterns, minimum size, removable policy.
• struct Partitioning
  • Alignment, emptiness requirement, bios_boot, esp, data, cache GPT names and sizes where applicable.
• struct BtrfsOptions
  • Compression string and raid profile (none or raid1).
• struct BcachefsOptions
  • Cache mode (promote or writeback), compression, checksum.
• struct VfatOptions
  • Reserved for ESP mkfs options; includes label ZOSBOOT.
• struct FsOptions
  • Aggregates BtrfsOptions, BcachefsOptions, VfatOptions and shared defaults such as ZOSDATA label.
• enum MountSchemeKind
  • Values: per_uuid, custom (future).
• struct MountScheme
  • Base directory (/var/cache), scheme kind, fstab enabled flag.
• struct ReportOptions
  • Output path (/run/zosstorage/state.json).

Configuration IO

• fn load_and_merge(cli: &Cli) -> Result
  • 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<()>
  • Ensures structural and semantic validity (e.g., disk selection rules not empty, sizes non-zero, supported topology combinations).

Device discovery

• struct Disk
  • Represents an eligible block device with path, size, rotational flag, and identifiers (serial, model if available).
• struct DeviceFilter
  • Derived from DeviceSelection; compiled regexes and size thresholds for efficient filtering.
• trait DeviceProvider
  • Abstraction for listing /dev and probing properties, enabling test doubles.
• fn discover(filter: &DeviceFilter) -> Result<Vec>
  • Returns eligible disks or a well-defined error if none are found.

Partitioning

• enum PartRole
  • Roles: BiosBoot, Esp, Data, Cache.
• struct PartitionSpec
  • 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
  • The planned set of PartitionSpec instances for a single Disk in the chosen topology.
• struct PartitionPlan
  • Combined plan across all target disks, including alignment rules and safety checks.
• struct PartitionResult
  • 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
  • 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>
  • Executes the plan via sgdisk and related utilities. Aborts if target disks are not empty or if signatures are detected.

Filesystems

• enum FsKind
  • Values: Vfat, Btrfs, Bcachefs.
• struct FsSpec
  • Maps PartitionResult to desired filesystem kind and label (ZOSBOOT for ESP; ZOSDATA for all data filesystems including bcachefs).
• struct FsPlan
  • Plan of mkfs operations across all partitions and devices given the topology.
• struct FsResult
  • Output of mkfs: device path(s), fs uuid, label, and kind.
• fn plan_filesystems(disks: &[Disk], parts: &[PartitionResult], cfg: &Config) -> Result
  • Determines which partitions receive vfat, btrfs, or bcachefs, and aggregates tuning options.
• fn make_filesystems(plan: &FsPlan, cfg: &Config) -> Result<Vec>
  • Invokes mkfs.vfat, mkfs.btrfs, mkfs.bcachefs accordingly via utility wrappers and returns filesystem identities.

Mounting

• struct MountPlan
  • 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
  • Actual mount operations performed (source, target, fstype, options).
• fn plan_mounts(fs_results: &[FsResult], cfg: &Config) -> Result
  • 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>
  • Performs mounts using syscalls (nix crate). Ensures directories exist and creates subvolumes/subdirs if missing.
• fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()>
  • 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
  • Version string for the JSON payload schema.
• struct StateReport
  • 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
  • Constructs a StateReport matching REPORT_VERSION.
• fn write_report(report: &StateReport) -> Result<()>
  • Writes JSON to /run/zosstorage/state.json (configurable).

Idempotency

• fn detect_existing_state() -> Result<Option>
  • 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
  • Determines disk emptiness: absence of partitions and known filesystem signatures.

Utilities

• struct CmdOutput
  • Captures status, stdout, stderr from external tool invocations.
• fn which_tool(name: &str) -> Result<Option>
  • Locates a required system utility in PATH, returning its absolute path if available.
• fn run_cmd(args: &[&str]) -> Result<()>
  • 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
  • Executes a command and returns captured output for parsing (e.g., blkid).
• fn udev_settle(timeout_ms: u64) -> Result<()>
  • Calls udevadm settle with a timeout when available; otherwise no-ops with a warning.
• fn is_efi_boot() -> bool
  • 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:
  • Partitioning strictly aborts on any pre-existing partition or filesystem signature when require_empty_disks is true.
  • Filesystem creation never proceeds if partitioning validation fails.
  • The orchestrator treats any partial progress as failure; state report is only written on success.
• Labels and GPT names:
  • ESP partitions are labeled ZOSBOOT (filesystem) and named zosboot (GPT).
  • Data filesystems use label ZOSDATA regardless of backend kind.
  • Cache partitions in bcachefs topology use GPT name zoscache.
• Topology-specific behavior:
  • 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).
  • bcachefs-2copy: 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

flowchart LR
  cli --> config
  config --> orchestrator
  logging --> orchestrator
  orchestrator --> idempotency
  orchestrator --> device
  device --> partition
  partition --> fs
  fs --> mount
  mount --> report
  orchestrator --> report
  util --> partition
  util --> fs
  util --> mount
  util --> idempotency

Status

• This API surface is ready for code-mode skeleton implementation with todo placeholders in function bodies and comprehensive doc comments.