feat(volumes): per-volume size cap (size=N[K|M|G])

[G4614]

Each shim has a virtro-blk mounted to the box so that a host-volume-cap is added for operations of each box
(optional)

Test plan

coverage	what it pins
parse_size_token_accepts_k_m_g_and_bare_bytes	K/M/G suffix (case-insensitive, binary multiples) + bare bytes + whitespace
parse_size_token_rejects_garbage_and_overflow	empty, negative, unsupported suffix (T), non-numeric, overflow
test_parse_volume_spec_anonymous_with_size	/data:size=10G → anon vol, size_bytes = 10 GiB
test_parse_volume_spec_anonymous_with_size_and_ro	/data:ro,size=500M and /data:size=500M,ro (order-independent)
test_parse_volume_spec_size_on_bind_rejected	/host:/box:size=10G → error: "size= is only valid on anonymous volumes"
test_parse_volume_spec_unknown_option_rejected	/data:zise=10G → error: "unknown volume option" (no silent typo drop)
existing test_parse_volume_spec_* (10)	regression: 2-part heuristic change ("second is ro/rw" → "second starts with /") preserves all existing accept/reject behavior, including the /data: trailing-colon rejection

cargo nextest run -p boxlite-cli -E 'test(~volume_spec) or test(~parse_size_token)' — 19/19 passed (0.06 s).

Summary by CodeRabbit

• New Features
  • Added support for sized volumes with configurable storage capacity limits using the -v <path>:size=N[K|M|G] syntax.
  • Sized volumes enforce write limits and prevent overflow with ENOSPC errors.
  • Support for read-only sized volumes with -v <path>:size=N,ro.
  • Volume data persists across stop/start cycles.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements sized volumes, a new feature enabling per-volume storage capacity limits via ext4 image files. The implementation spans schema updates, image creation and resolution, box startup integration, guest-side mounting, CLI parsing, and comprehensive integration testing.

Changes

Sized Volumes Feature

Layer / File(s)	Summary
Core schema and type contracts src/boxlite/src/runtime/options.rs, src/shared/proto/boxlite/v1/service.proto, src/boxlite/src/portal/interfaces/guest.rs, src/boxlite/src/litebox/init/types.rs	VolumeSpec gains optional size_bytes field; ResolvedVolume tracks capacity for sized vs. legacy volumes; BlockDeviceSource protobuf adds read_only flag; VolumeConfig::BlockDevice variant includes read_only to support read-only mounting.
SDK bridges for sized volumes sdks/c/src/options.rs, sdks/node/src/options.rs, sdks/python/src/options.rs	C, Node, and Python SDKs initialize size_bytes: None on core VolumeSpec with documentation that sizing is not yet exposed via these APIs.
Sized volume image creation utility src/boxlite/src/runtime/mod.rs, src/boxlite/src/runtime/sized_volume.rs	New sized_volume.rs module exports create_sized_volume_image with ext4 sizing policy constants, sparse image creation, in-place mke2fs formatting, statvfs-based overcommit prevention, and unit tests verifying size validation and image integrity.
Volume resolution with sized volume materialization src/boxlite/src/litebox/init/types.rs	resolve_user_volumes refactored to materialize sized volumes as persistent ext4 .img files while preserving legacy directory-backed volumes; test coverage extended for image creation, reuse, and sized-volume contract enforcement.
Block device mounting with read-only support src/guest/src/storage/block_device.rs, src/guest/src/storage/volume.rs, src/guest/src/service/container.rs	BlockDeviceMount::mount signature extended with read_only parameter, conditionally applying MS_RDONLY flag; guest container init always mounts rootfs writable to ensure root filesystem availability.
VMM spawn integration for sized volumes src/boxlite/Cargo.toml, src/boxlite/src/litebox/init/tasks/vmm_spawn.rs	Enables nix crate fs feature; build_config derives per-box sized_volumes_dir, materializes sized user volumes as ext4 block devices via volume_mgr, and replays as bind mounts before legacy virtiofs volumes.
Guest volume manager block device configuration src/boxlite/src/volumes/guest_volume.rs	GuestVolumeManager::build_guest_mounts passes block entry's read_only flag into VolumeConfig::block_device constructor.
CLI parsing for size= option on anonymous volumes src/cli/src/cli.rs	Introduces parse_size_token helper for N[K|M|G] + bare-byte parsing; VolumeOptions parser handles ro/rw/size=... flags; parse_volume_spec refactored to distinguish anonymous vs. bind-mount volumes, reject size= on bind mounts, and validate unknown options; parsed size_bytes wired into VolumeSpec.
End-to-end integration test suite src/cli/tests/sized_volume.rs	Five end-to-end scenarios: (1) capacity capping and host cleanup, (2) volume independence, (3) persistence across stop/start, (4) no resource starvation, (5) read-only enforcement.
Unit test updates for struct field additions src/boxlite/src/jailer/builder.rs, src/boxlite/src/jailer/command.rs, src/boxlite/src/jailer/mod.rs, src/boxlite/tests/mount_security.rs, src/boxlite/tests/security_enforcement.rs	Jailer and integration tests updated to include explicit size_bytes: None in VolumeSpec literals.

🎯 4 (Complex) | ⏱️ ~60 minutes

🐰 A hopping new volume appears,
Sized and bounded, no overflow fears!
Ext4 images spark to life,
Guest writes capped without strife,
The box grows wise with storage might!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(volumes): per-volume size cap (size=N[K|M|G])' clearly and specifically describes the main change—adding per-volume storage size capacity limits with CLI syntax.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ G4614
❌ Ubuntu

---

Ubuntu seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Actionable comments posted: 4

🧹 Nitpick comments (1)

src/boxlite/src/runtime/sized_volume.rs (1)

77-77: 💤 Low value

Confirm fragment_size() type and keep overflow check as optional

nix::sys::statvfs::Statvfs::fragment_size() returns c_ulong, so the multiplication at src/boxlite/src/runtime/sized_volume.rs (line 77) is type-consistent with blocks_available() being c_ulong (cast to u64). Using checked_mul would be purely defensive hardening; it isn’t required to fix a type/API mismatch.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/boxlite/src/runtime/sized_volume.rs` at line 77, Confirm that
Statvfs::fragment_size() returns c_ulong and that blocks_available() is cast to
u64 already; keep the current multiplication but optionally harden it by using a
checked multiplication when computing free_bytes in sized_volume.rs (the
expression assigning to free_bytes that uses vfs.blocks_available() and
vfs.fragment_size()). If you add the defensive check, use checked_mul on the u64
operands and handle the None case (e.g., cap at u64::MAX or return an error) so
overflow is handled explicitly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/boxlite/src/litebox/init/types.rs`:
- Around line 72-73: The tag creation using the loop index ("tag =
format!(\"uservol{}\", i)") is unstable and can mismatch volumes if order
changes; instead derive a stable tag from the volume identity (e.g., sanitize
vol.guest_path or compute a short hash of vol.guest_path and other identifying
fields like vol.size) so the filename remains tied to the mount target rather
than array position—replace the index-based tag with a deterministic tag using
vol.guest_path (or hash of guest_path+size) and ensure any sanitization yields a
filesystem-safe string before using it as the tag/filename.

In `@src/cli/src/cli.rs`:
- Around line 564-570: The function parse_size_token currently parses num_part
into a u64 but allows zero; add a check after parsing to reject 0 so the CLI
enforces "positive integer" semantics early. Specifically, in parse_size_token
(the block that parses num_part into num), after the parse succeeds do if num ==
0 { return Err(anyhow::anyhow!("size must be a positive integer, got {:?}",
num_part)); } before performing num.checked_mul(mult). Ensure the error message
and returned Err match the existing style and still reference the original token
(num_part or s) as in the surrounding code.
- Around line 670-675: The Windows-drive parsing branch currently accepts
four-or-more segments and ignores parts[4..], which can hide malformed specs; in
the 4.. branch (where is_windows_drive(parts[0]) is true) validate that
parts.len() == 4 and, if greater, return an error instead of proceeding—locate
the logic around is_windows_drive and VolumeOptions::parse(parts[3]) and add a
check to reject inputs with extra ':' segments (produce a clear parse error
message) so malformed Windows volume specs are not silently accepted.

In `@src/cli/tests/sized_volume.rs`:
- Around line 233-250: The code currently silences failures by using
.unwrap_or(0) when parsing df output into b_avail_before; change this to fail
fast: after running boxlite(...) capture the stdout string and call
parse::<u64>().expect(...) (or explicitly match the Result and panic) so the
test errors out with a clear message including the raw stdout when df/exec/parse
fails; reference the b_avail_before binding and the boxlite(...) call that
produces o.stdout to locate the change.

---

Nitpick comments:
In `@src/boxlite/src/runtime/sized_volume.rs`:
- Line 77: Confirm that Statvfs::fragment_size() returns c_ulong and that
blocks_available() is cast to u64 already; keep the current multiplication but
optionally harden it by using a checked multiplication when computing free_bytes
in sized_volume.rs (the expression assigning to free_bytes that uses
vfs.blocks_available() and vfs.fragment_size()). If you add the defensive check,
use checked_mul on the u64 operands and handle the None case (e.g., cap at
u64::MAX or return an error) so overflow is handled explicitly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 61669e98-1684-4151-b44c-0dc589a779b2

📥 Commits

Reviewing files that changed from the base of the PR and between f21e5a4 and ad8bc48.

📒 Files selected for processing (22)

• sdks/c/src/options.rs
• sdks/node/src/options.rs
• sdks/python/src/options.rs
• src/boxlite/Cargo.toml
• src/boxlite/src/jailer/builder.rs
• src/boxlite/src/jailer/command.rs
• src/boxlite/src/jailer/mod.rs
• src/boxlite/src/litebox/init/tasks/vmm_spawn.rs
• src/boxlite/src/litebox/init/types.rs
• src/boxlite/src/portal/interfaces/guest.rs
• src/boxlite/src/runtime/mod.rs
• src/boxlite/src/runtime/options.rs
• src/boxlite/src/runtime/sized_volume.rs
• src/boxlite/src/volumes/guest_volume.rs
• src/boxlite/tests/mount_security.rs
• src/boxlite/tests/security_enforcement.rs
• src/cli/src/cli.rs
• src/cli/tests/sized_volume.rs
• src/guest/src/service/container.rs
• src/guest/src/storage/block_device.rs
• src/guest/src/storage/volume.rs
• src/shared/proto/boxlite/v1/service.proto

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Tag derivation from index position could cause data mismatch if volume order changes.

The tag uservol{i} is derived from the volume's position in the array. If a user reorders volumes between restarts (e.g., swaps -v /a:size=16M -v /b:size=32M to -v /b:size=32M -v /a:size=16M), the existing uservol0.img (originally for /a) would be reused for /b, potentially exposing the wrong data at the wrong mount point.

Consider deriving the tag from the guest_path (sanitized) or a hash of identifying properties to ensure stable mapping across restarts.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/boxlite/src/litebox/init/types.rs` around lines 72 - 73, The tag creation
using the loop index ("tag = format!(\"uservol{}\", i)") is unstable and can
mismatch volumes if order changes; instead derive a stable tag from the volume
identity (e.g., sanitize vol.guest_path or compute a short hash of
vol.guest_path and other identifying fields like vol.size) so the filename
remains tied to the mount target rather than array position—replace the
index-based tag with a deterministic tag using vol.guest_path (or hash of
guest_path+size) and ensure any sanitization yields a filesystem-safe string
before using it as the tag/filename.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

parse_size_token says “positive integer” but currently accepts 0.

0 passes parse and only fails later in runtime admission, which weakens CLI-level validation and gives less direct feedback.

Suggested fix

     let num: u64 = num_part
         .trim()
         .parse()
         .map_err(|_| anyhow::anyhow!("size must be a positive integer, got {:?}", num_part))?;
+    if num == 0 {
+        anyhow::bail!("size must be greater than 0");
+    }
     num.checked_mul(mult)
         .ok_or_else(|| anyhow::anyhow!("size overflow: {:?}", s))

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	let num: u64 = num_part
	.trim()
	.parse()
	.map_err(|_| anyhow::anyhow!("size must be a positive integer, got {:?}", num_part))?;
	num.checked_mul(mult)
	.ok_or_else(|| anyhow::anyhow!("size overflow: {:?}", s))
	}
	let num: u64 = num_part
	.trim()
	.parse()
	.map_err(|_| anyhow::anyhow!("size must be a positive integer, got {:?}", num_part))?;
	if num == 0 {
	anyhow::bail!("size must be greater than 0");
	}
	num.checked_mul(mult)
	.ok_or_else(|| anyhow::anyhow!("size overflow: {:?}", s))
	}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/src/cli.rs` around lines 564 - 570, The function parse_size_token
currently parses num_part into a u64 but allows zero; add a check after parsing
to reject 0 so the CLI enforces "positive integer" semantics early.
Specifically, in parse_size_token (the block that parses num_part into num),
after the parse succeeds do if num == 0 { return Err(anyhow::anyhow!("size must
be a positive integer, got {:?}", num_part)); } before performing
num.checked_mul(mult). Ensure the error message and returned Err match the
existing style and still reference the original token (num_part or s) as in the
surrounding code.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Reject Windows volume specs with extra : segments instead of silently ignoring them.

For Windows-drive inputs in the 4.. branch, only parts[3] is parsed as options and any parts[4..] are ignored. This can silently accept malformed specs and hide typos/options you intended to reject.

Suggested fix

-        4.. => {
+        4 => {
             if is_windows_drive(parts[0]) {
                 let host = format!("{}:{}", parts[0], parts[1]);
                 let opts = VolumeOptions::parse(parts[3])?;
                 (Some(host), parts[2].to_string(), opts)
             } else {
                 anyhow::bail!(
                     "invalid volume spec {:?}; use hostPath:boxPath[:options] (e.g. /data:/app/data or C:\\data:/app/data:ro)",
                     s
                 );
             }
         }
+        5.. => {
+            anyhow::bail!(
+                "invalid volume spec {:?}; too many ':' segments in volume spec",
+                s
+            );
+        }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/src/cli.rs` around lines 670 - 675, The Windows-drive parsing branch
currently accepts four-or-more segments and ignores parts[4..], which can hide
malformed specs; in the 4.. branch (where is_windows_drive(parts[0]) is true)
validate that parts.len() == 4 and, if greater, return an error instead of
proceeding—locate the logic around is_windows_drive and
VolumeOptions::parse(parts[3]) and add a check to reject inputs with extra ':'
segments (produce a clear parse error message) so malformed Windows volume specs
are not silently accepted.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Don’t default b_avail_before to 0; fail fast on bad df output.

Using .unwrap_or(0) can hide exec/parse failures and let this isolation test pass incorrectly.

Suggested fix

     let b_avail_before = {
         let o = boxlite(
             home.path.as_path(),
             &[
                 "exec",
                 &box_id,
                 "--",
                 "sh",
                 "-c",
                 "df -P /b | awk 'NR==2{print $4}'",
             ],
             Duration::from_secs(20),
         );
-        String::from_utf8_lossy(&o.stdout)
+        assert!(
+            o.status.success(),
+            "failed to read /b available space before fill: {}",
+            String::from_utf8_lossy(&o.stderr)
+        );
+        String::from_utf8_lossy(&o.stdout)
             .trim()
             .parse::<u64>()
-            .unwrap_or(0)
+            .unwrap_or_else(|_| panic!("invalid /b available-space output: {:?}", String::from_utf8_lossy(&o.stdout)))
     };

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	let b_avail_before = {
	let o = boxlite(
	home.path.as_path(),
	&[
	"exec",
	&box_id,
	"--",
	"sh",
	"-c",
	"df -P /b | awk 'NR==2{print $4}'",
	],
	Duration::from_secs(20),
	);
	String::from_utf8_lossy(&o.stdout)
	.trim()
	.parse::<u64>()
	.unwrap_or(0)
	};
	let b_avail_before = {
	let o = boxlite(
	home.path.as_path(),
	&[
	"exec",
	&box_id,
	"--",
	"sh",
	"-c",
	"df -P /b | awk 'NR==2{print $4}'",
	],
	Duration::from_secs(20),
	);
	assert!(
	o.status.success(),
	"failed to read /b available space before fill: {}",
	String::from_utf8_lossy(&o.stderr)
	);
	String::from_utf8_lossy(&o.stdout)
	.trim()
	.parse::<u64>()
	.unwrap_or_else(|_| panic!("invalid /b available-space output: {:?}", String::from_utf8_lossy(&o.stdout)))
	};

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/cli/tests/sized_volume.rs` around lines 233 - 250, The code currently
silences failures by using .unwrap_or(0) when parsing df output into
b_avail_before; change this to fail fast: after running boxlite(...) capture the
stdout string and call parse::<u64>().expect(...) (or explicitly match the
Result and panic) so the test errors out with a clear message including the raw
stdout when df/exec/parse fails; reference the b_avail_before binding and the
boxlite(...) call that produces o.stdout to locate the change.

[G4614]

wait for #639