tfgrid/zosstorage
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: sync with code (topologies, mount scheme, CLI flags, UEFI/BIOS, fstab) and fix relative src links in docs/ to ../src/

Browse Source
This commit is contained in:
Jan De Landtsheer
2025-09-29 23:24:25 +02:00
parent 7cef73368b
commit b0d8c0bc75
9 changed files with 451 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
docs/API-SKELETONS.md
View File

@@ -6,34 +6,34 @@ Purpose
- After approval, these will be created in the src tree in Code mode.
Index
- [src/lib.rs](src/lib.rs)
- [src/errors.rs](src/errors.rs)
- [src/main.rs](src/main.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/lib.rs](../src/lib.rs)
- [src/errors.rs](../src/errors.rs)
- [src/main.rs](../src/main.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)
Conventions
- Shared [type Result<T>](src/errors.rs:1) and [enum Error](src/errors.rs:1).
- Shared [type Result<T>](../src/errors.rs:1) and [enum Error](../src/errors.rs:1).
- No stdout prints; use tracing only.
- External tools invoked via [util](src/util/mod.rs) wrappers.
- External tools invoked via [util](../src/util/mod.rs) wrappers.
---
## Crate root
References
- [src/lib.rs](src/lib.rs)
- [type Result<T> = std::result::Result<T, Error>](src/errors.rs:1)
- [src/lib.rs](../src/lib.rs)
- [type Result<T> = std::result::Result<T, Error>](../src/errors.rs:1)
Skeleton (for later implementation in code mode)
```rust
@@ -63,8 +63,8 @@ pub const VERSION: &str = env!("CARGO_PKG_VERSION");
## Errors
References
- [enum Error](src/errors.rs:1)
- [type Result<T>](src/errors.rs:1)
- [enum Error](../src/errors.rs:1)
- [type Result<T>](../src/errors.rs:1)
Skeleton
```rust
@@ -107,8 +107,8 @@ pub type Result<T> = std::result::Result<T, Error>;
## Entrypoint
References
- [fn main()](src/main.rs:1)
- [fn run(ctx: &Context) -> Result<()>](src/orchestrator/run.rs:1)
- [fn main()](../src/main.rs:1)
- [fn run(ctx: &Context) -> Result<()>](../src/orchestrator/run.rs:1)
Skeleton
```rust
@@ -143,8 +143,8 @@ fn real_main() -> Result<()> {
## CLI
References
- [struct Cli](src/cli/args.rs:1)
- [fn from_args() -> Cli](src/cli/args.rs:1)
- [struct Cli](../src/cli/args.rs:1)
- [fn from_args() -> Cli](../src/cli/args.rs:1)
Skeleton
```rust
@@ -170,6 +170,18 @@ pub struct Cli {
#[arg(long = "fstab", default_value_t = false)]
pub fstab: bool,
/// Print preview JSON to stdout (non-destructive)
#[arg(long = "show", default_value_t = false)]
pub show: bool,
/// Write preview JSON to a file (non-destructive)
#[arg(long = "report")]
pub report: Option<String>,
/// Perform partitioning, filesystem creation, and mounts (DESTRUCTIVE)
#[arg(long = "apply", default_value_t = false)]
pub apply: bool,
/// Present but non-functional; returns unimplemented error
#[arg(long = "force")]
pub force: bool,
@@ -186,8 +198,8 @@ pub fn from_args() -> Cli {
## Logging
References
- [struct LogOptions](src/logging/mod.rs:1)
- [fn init_logging(opts: &LogOptions) -> Result<()>](src/logging/mod.rs:1)
- [struct LogOptions](../src/logging/mod.rs:1)
- [fn init_logging(opts: &LogOptions) -> Result<()>](../src/logging/mod.rs:1)
Skeleton
```rust
@@ -218,13 +230,13 @@ pub fn init_logging(opts: &LogOptions) -> Result<()> {
## Configuration types
References
- [struct Config](src/types.rs:1)
- [enum Topology](src/types.rs:1)
- [struct DeviceSelection](src/types.rs:1)
- [struct Partitioning](src/types.rs:1)
- [struct FsOptions](src/types.rs:1)
- [struct MountScheme](src/types.rs:1)
- [struct ReportOptions](src/types.rs:1)
- [struct Config](../src/types.rs:1)
- [enum Topology](../src/types.rs:1)
- [struct DeviceSelection](../src/types.rs:1)
- [struct Partitioning](../src/types.rs:1)
- [struct FsOptions](../src/types.rs:1)
- [struct MountScheme](../src/types.rs:1)
- [struct ReportOptions](../src/types.rs:1)
Skeleton
```rust
@@ -247,8 +259,10 @@ pub struct DeviceSelection {
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Topology {
Single,
BtrfsSingle,
BcachefsSingle,
DualIndependent,
Bcachefs2Copy,
SsdHddBcachefs,
BtrfsRaid1,
}
@@ -351,8 +365,8 @@ pub struct Config {
## Configuration I/O
References
- [fn load_and_merge(cli: &Cli) -> Result<Config>](src/config/loader.rs:1)
- [fn validate(cfg: &Config) -> Result<()>](src/config/loader.rs:1)
- [fn load_and_merge(cli: &Cli) -> Result<Config>](../src/config/loader.rs:1)
- [fn validate(cfg: &Config) -> Result<()>](../src/config/loader.rs:1)
Skeleton
```rust
@@ -374,10 +388,10 @@ pub fn validate(cfg: &crate::config::types::Config) -> Result<()> {
## Device discovery
References
- [struct Disk](src/device/discovery.rs:1)
- [struct DeviceFilter](src/device/discovery.rs:1)
- [trait DeviceProvider](src/device/discovery.rs:1)
- [fn discover(filter: &DeviceFilter) -> Result<Vec<Disk>>](src/device/discovery.rs:1)
- [struct Disk](../src/device/discovery.rs:1)
- [struct DeviceFilter](../src/device/discovery.rs:1)
- [trait DeviceProvider](../src/device/discovery.rs:1)
- [fn discover(filter: &DeviceFilter) -> Result<Vec<Disk>>](../src/device/discovery.rs:1)
Skeleton
```rust
@@ -418,12 +432,12 @@ pub fn discover(filter: &DeviceFilter) -> Result<Vec<Disk>> {
## Partitioning
References
- [enum PartRole](src/partition/plan.rs:1)
- [struct PartitionSpec](src/partition/plan.rs:1)
- [struct PartitionPlan](src/partition/plan.rs:1)
- [struct PartitionResult](src/partition/plan.rs:1)
- [fn plan_partitions(disks: &[Disk], cfg: &Config) -> Result<PartitionPlan>](src/partition/plan.rs:1)
- [fn apply_partitions(plan: &PartitionPlan) -> Result<Vec<PartitionResult>>](src/partition/plan.rs:1)
- [enum PartRole](../src/partition/plan.rs:1)
- [struct PartitionSpec](../src/partition/plan.rs:1)
- [struct PartitionPlan](../src/partition/plan.rs:1)
- [struct PartitionResult](../src/partition/plan.rs:1)
- [fn plan_partitions(disks: &[Disk], cfg: &Config) -> Result<PartitionPlan>](../src/partition/plan.rs:1)
- [fn apply_partitions(plan: &PartitionPlan) -> Result<Vec<PartitionResult>>](../src/partition/plan.rs:1)
Skeleton
```rust
@@ -485,12 +499,12 @@ pub fn apply_partitions(plan: &PartitionPlan) -> Result<Vec<PartitionResult>> {
## Filesystems
References
- [enum FsKind](src/fs/plan.rs:1)
- [struct FsSpec](src/fs/plan.rs:1)
- [struct FsPlan](src/fs/plan.rs:1)
- [struct FsResult](src/fs/plan.rs:1)
- [fn plan_filesystems(...)](src/fs/plan.rs:1)
- [fn make_filesystems(...)](src/fs/plan.rs:1)
- [enum FsKind](../src/fs/plan.rs:1)
- [struct FsSpec](../src/fs/plan.rs:1)
- [struct FsPlan](../src/fs/plan.rs:1)
- [struct FsResult](../src/fs/plan.rs:1)
- [fn plan_filesystems(...)](../src/fs/plan.rs:1)
- [fn make_filesystems(...)](../src/fs/plan.rs:1)
Skeleton
```rust
@@ -531,8 +545,8 @@ pub fn plan_filesystems(
todo!("map ESP to vfat, data to btrfs or bcachefs according to topology")
}
/// Create the filesystems and return identity info (UUIDs, labels).
pub fn make_filesystems(plan: &FsPlan) -> Result<Vec<FsResult>> {
//// Create the filesystems and return identity info (UUIDs, labels).
pub fn make_filesystems(plan: &FsPlan, cfg: &Config) -> Result<Vec<FsResult>> {
todo!("invoke mkfs tools with configured options via util::run_cmd")
}
```
@@ -542,11 +556,11 @@ pub fn make_filesystems(plan: &FsPlan) -> Result<Vec<FsResult>> {
## Mounting
References
- [struct MountPlan](src/mount/ops.rs:1)
- [struct MountResult](src/mount/ops.rs:1)
- [fn plan_mounts(...)](src/mount/ops.rs:1)
- [fn apply_mounts(...)](src/mount/ops.rs:1)
- [fn maybe_write_fstab(...)](src/mount/ops.rs:1)
- [struct MountPlan](../src/mount/ops.rs:1)
- [struct MountResult](../src/mount/ops.rs:1)
- [fn plan_mounts(...)](../src/mount/ops.rs:1)
- [fn apply_mounts(...)](../src/mount/ops.rs:1)
- [fn maybe_write_fstab(...)](../src/mount/ops.rs:1)
Skeleton
```rust
@@ -565,9 +579,13 @@ pub struct MountResult {
pub options: String,
}
/// Build mount plan under /var/cache/<UUID> by default.
//// Build mount plan:
//// - Root-mount all data filesystems under `/var/mounts/{UUID}` (runtime only)
//// - Ensure/create subvolumes on the primary data filesystem: system, etc, modules, vm-meta
//// - Plan final mounts to `/var/cache/{system,etc,modules,vm-meta}` using
//// `subvol=` for btrfs and `X-mount.subdir=` for bcachefs.
pub fn plan_mounts(fs_results: &[FsResult], cfg: &Config) -> Result<MountPlan> {
todo!("create per-UUID directories and mount mapping")
todo!("root mounts under /var/mounts/{UUID}; final subvol/subdir mounts to /var/cache/{system,etc,modules,vm-meta}")
}
/// Apply mounts using syscalls (nix), ensuring directories exist.
@@ -575,9 +593,12 @@ pub fn apply_mounts(plan: &MountPlan) -> Result<Vec<MountResult>> {
todo!("perform mount syscalls and return results")
}
/// Optionally generate /etc/fstab entries in deterministic order.
//// Optionally generate /etc/fstab entries for final subvolume/subdir mounts only.
//// - Write exactly four entries: system, etc, modules, vm-meta
//// - Use UUID= sources; deterministic order by target path
//// - Exclude runtime root mounts under `/var/mounts/{UUID}`
pub fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()> {
todo!("when enabled, write fstab entries")
todo!("when enabled, write only the four final subvolume/subdir entries with UUID= sources")
}
```
@@ -586,10 +607,10 @@ pub fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config) -> Result<()> {
## Reporting
References
- [const REPORT_VERSION: &str](src/report/state.rs:1)
- [struct StateReport](src/report/state.rs:1)
- [fn build_report(...)](src/report/state.rs:1)
- [fn write_report(...)](src/report/state.rs:1)
- [const REPORT_VERSION: &str](../src/report/state.rs:1)
- [struct StateReport](../src/report/state.rs:1)
- [fn build_report(...)](../src/report/state.rs:1)
- [fn write_report(...)](../src/report/state.rs:1)
Skeleton
```rust
@@ -632,8 +653,8 @@ pub fn write_report(report: &StateReport, path: &str) -> Result<()> {
## Orchestrator
References
- [struct Context](src/orchestrator/run.rs:1)
- [fn run(ctx: &Context) -> Result<()>](src/orchestrator/run.rs:1)
- [struct Context](../src/orchestrator/run.rs:1)
- [fn run(ctx: &Context) -> Result<()>](../src/orchestrator/run.rs:1)
Skeleton
```rust
@@ -662,8 +683,8 @@ pub fn run(ctx: &Context) -> Result<()> {
## Idempotency
References
- [fn detect_existing_state() -> Result<Option<StateReport>>](src/idempotency/mod.rs:1)
- [fn is_empty_disk(disk: &Disk) -> Result<bool>](src/idempotency/mod.rs:1)
- [fn detect_existing_state() -> Result<Option<StateReport>>](../src/idempotency/mod.rs:1)
- [fn is_empty_disk(disk: &Disk) -> Result<bool>](../src/idempotency/mod.rs:1)
Skeleton
```rust
@@ -685,11 +706,11 @@ pub fn is_empty_disk(disk: &Disk) -> Result<bool> {
## Utilities
References
- [struct CmdOutput](src/util/mod.rs:1)
- [fn which_tool(name: &str) -> Result<Option<String>>](src/util/mod.rs:1)
- [fn run_cmd(args: &[&str]) -> Result<()>](src/util/mod.rs:1)
- [fn run_cmd_capture(args: &[&str]) -> Result<CmdOutput>](src/util/mod.rs:1)
- [fn udev_settle(timeout_ms: u64) -> Result<()>](src/util/mod.rs:1)
- [struct CmdOutput](../src/util/mod.rs:1)
- [fn which_tool(name: &str) -> Result<Option<String>>](../src/util/mod.rs:1)
- [fn run_cmd(args: &[&str]) -> Result<()>](../src/util/mod.rs:1)
- [fn run_cmd_capture(args: &[&str]) -> Result<CmdOutput>](../src/util/mod.rs:1)
- [fn udev_settle(timeout_ms: u64) -> Result<()>](../src/util/mod.rs:1)
Skeleton
```rust
@@ -722,6 +743,11 @@ pub fn run_cmd_capture(args: &[&str]) -> Result<CmdOutput> {
pub fn udev_settle(timeout_ms: u64) -> Result<()> {
todo!("invoke udevadm settle when present")
}
/// Detect UEFI environment by checking /sys/firmware/efi; used to suppress BIOS boot partition on UEFI.
pub fn is_efi_boot() -> bool {
todo!("return Path::new(\"/sys/firmware/efi\").exists()")
}
```
---
@@ -735,24 +761,24 @@ Approval gate
- Add initial tests scaffolding and example configs.
References summary
- [fn main()](src/main.rs:1)
- [fn from_args()](src/cli/args.rs:1)
- [fn init_logging(opts: &LogOptions)](src/logging/mod.rs:1)
- [fn load_and_merge(cli: &Cli)](src/config/loader.rs:1)
- [fn validate(cfg: &Config)](src/config/loader.rs:1)
- [fn discover(filter: &DeviceFilter)](src/device/discovery.rs:1)
- [fn plan_partitions(disks: &[Disk], cfg: &Config)](src/partition/plan.rs:1)
- [fn apply_partitions(plan: &PartitionPlan)](src/partition/plan.rs:1)
- [fn plan_filesystems(parts: &[PartitionResult], cfg: &Config)](src/fs/plan.rs:1)
- [fn make_filesystems(plan: &FsPlan)](src/fs/plan.rs:1)
- [fn plan_mounts(fs_results: &[FsResult], cfg: &Config)](src/mount/ops.rs:1)
- [fn apply_mounts(plan: &MountPlan)](src/mount/ops.rs:1)
- [fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config)](src/mount/ops.rs:1)
- [fn build_report(...)](src/report/state.rs:1)
- [fn write_report(report: &StateReport)](src/report/state.rs:1)
- [fn detect_existing_state()](src/idempotency/mod.rs:1)
- [fn is_empty_disk(disk: &Disk)](src/idempotency/mod.rs:1)
- [fn which_tool(name: &str)](src/util/mod.rs:1)
- [fn run_cmd(args: &[&str])](src/util/mod.rs:1)
- [fn run_cmd_capture(args: &[&str])](src/util/mod.rs:1)
- [fn udev_settle(timeout_ms: u64)](src/util/mod.rs:1)
- [fn main()](../src/main.rs:1)
- [fn from_args()](../src/cli/args.rs:1)
- [fn init_logging(opts: &LogOptions)](../src/logging/mod.rs:1)
- [fn load_and_merge(cli: &Cli)](../src/config/loader.rs:1)
- [fn validate(cfg: &Config)](../src/config/loader.rs:1)
- [fn discover(filter: &DeviceFilter)](../src/device/discovery.rs:1)
- [fn plan_partitions(disks: &[Disk], cfg: &Config)](../src/partition/plan.rs:1)
- [fn apply_partitions(plan: &PartitionPlan)](../src/partition/plan.rs:1)
- [fn plan_filesystems(parts: &[PartitionResult], cfg: &Config)](../src/fs/plan.rs:1)
- [fn make_filesystems(plan: &FsPlan)](../src/fs/plan.rs:1)
- [fn plan_mounts(fs_results: &[FsResult], cfg: &Config)](../src/mount/ops.rs:1)
- [fn apply_mounts(plan: &MountPlan)](../src/mount/ops.rs:1)
- [fn maybe_write_fstab(mounts: &[MountResult], cfg: &Config)](../src/mount/ops.rs:1)
- [fn build_report(...)](../src/report/state.rs:1)
- [fn write_report(report: &StateReport)](../src/report/state.rs:1)
- [fn detect_existing_state()](../src/idempotency/mod.rs:1)
- [fn is_empty_disk(disk: &Disk)](../src/idempotency/mod.rs:1)
- [fn which_tool(name: &str)](../src/util/mod.rs:1)
- [fn run_cmd(args: &[&str])](../src/util/mod.rs:1)
- [fn run_cmd_capture(args: &[&str])](../src/util/mod.rs:1)
- [fn udev_settle(timeout_ms: u64)](../src/util/mod.rs:1)