From 4c95935ebe965ab71853262cd0e88cab0341db69 Mon Sep 17 00:00:00 2001 From: M3gA-Mind Date: Wed, 11 Nov 2026 17:03:16 +0530 Subject: [PATCH] Make a resource budget's disk limit optional (contract 2.6) ResourceLimits.disk_bytes was a required u64 defaulting to 8 GiB, and an explicit native jail budget turned it into a hard Disk requirement that no backend enforces, so every legacy jail request with resources was refused. disk_bytes is now Option, absent by default and on the wire when unset. A native jail requires Disk only when the caller sets one; a box keeps the soft core default. Contract 2.6, since a module before it cannot decode a budget without the field. --- crates/tinybox-bus/src/event_tests.rs | 2 +- crates/tinybox-bus/src/jail_tests.rs | 2 +- crates/tinybox-bus/src/lib.rs | 16 +++++--- crates/tinybox-bus/src/lib_tests.rs | 37 ++++++++++++++++--- .../src/tinybus_module/native_jail.rs | 27 ++++++++------ .../src/tinybus_module/native_jail_tests.rs | 25 ++++++++++++- .../src/tinybus_module/resources.rs | 7 +++- .../src/tinybus_module/resources_tests.rs | 21 ++++++++++- docs/specs/contract-2-6.md | 23 ++++++++++++ 9 files changed, 132 insertions(+), 28 deletions(-) create mode 100644 docs/specs/contract-2-6.md diff --git a/crates/tinybox-bus/src/event_tests.rs b/crates/tinybox-bus/src/event_tests.rs index 664941ab..c9fb10fe 100644 --- a/crates/tinybox-bus/src/event_tests.rs +++ b/crates/tinybox-bus/src/event_tests.rs @@ -44,7 +44,7 @@ fn process_events_keep_their_correlation_and_signal_wire_shape() -> Result<(), s ); assert_eq!(names::PROCESS_EVENT, "ProcessEvent"); assert_eq!(SIGNALS, &["ProcessEvent"]); - assert_eq!(CONTRACT_VERSION, (2, 5)); + assert_eq!(CONTRACT_VERSION, (2, 6)); Ok(()) } diff --git a/crates/tinybox-bus/src/jail_tests.rs b/crates/tinybox-bus/src/jail_tests.rs index 54551483..fb55909d 100644 --- a/crates/tinybox-bus/src/jail_tests.rs +++ b/crates/tinybox-bus/src/jail_tests.rs @@ -60,7 +60,7 @@ fn native_resource_limits_are_optional_typed_and_round_trip() -> Result<(), serd cpu_millis: 500, memory_bytes: 1_048_576, pids_max: 32, - disk_bytes: 10_485_760, + disk_bytes: Some(10_485_760), }) ); assert_eq!(serde_json::to_value(config)?, request); diff --git a/crates/tinybox-bus/src/lib.rs b/crates/tinybox-bus/src/lib.rs index 392a662b..5ab063f0 100644 --- a/crates/tinybox-bus/src/lib.rs +++ b/crates/tinybox-bus/src/lib.rs @@ -91,8 +91,10 @@ pub use files::{ /// its owner across uses; the `agent37` backend honours it and every other /// backend refuses it. 2.5 adds [`NativeJailConfig::deny_read_names`], read /// denials by file name that only a backend able to deny by name admits, and a -/// most-restrictive `Default` for [`NativeJailConfig`]. -pub const CONTRACT_VERSION: (u32, u32) = (2, 5); +/// most-restrictive `Default` for [`NativeJailConfig`]. 2.6 makes +/// [`ResourceLimits::disk_bytes`] optional and absent by default; a host must +/// bind a 2.6 module before it omits the field. +pub const CONTRACT_VERSION: (u32, u32) = (2, 6); /// Minimum contract version required for resource-aware native jail members. pub const NATIVE_JAIL_RESOURCES_VERSION: (u32, u32) = (2, 1); @@ -438,8 +440,12 @@ pub struct ResourceLimits { pub memory_bytes: u64, /// Maximum number of processes and threads. pub pids_max: u32, - /// Maximum writable filesystem size in bytes. - pub disk_bytes: u64, + /// Maximum writable filesystem size in bytes. Optional from contract 2.6, + /// and absent by default: no backend enforces a disk budget, so a value + /// is a request a native jail must refuse rather than a default it + /// pretends to apply. Absent on the wire when `None`. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub disk_bytes: Option, } impl Default for ResourceLimits { @@ -448,7 +454,7 @@ impl Default for ResourceLimits { cpu_millis: 2_000, memory_bytes: 2 * 1024 * 1024 * 1024, pids_max: 512, - disk_bytes: 8 * 1024 * 1024 * 1024, + disk_bytes: None, } } } diff --git a/crates/tinybox-bus/src/lib_tests.rs b/crates/tinybox-bus/src/lib_tests.rs index 120d1ee7..28411427 100644 --- a/crates/tinybox-bus/src/lib_tests.rs +++ b/crates/tinybox-bus/src/lib_tests.rs @@ -59,7 +59,7 @@ fn docker_run_vocabulary_is_typed_bounded_and_additive() -> Result<(), serde_jso assert_eq!(METHODS[28], "CleanupDocker"); assert_eq!(METHODS[29], "RunDockerWithoutWorkspace"); assert_eq!(METHODS[33], "StartNativeShellExec"); - assert_eq!(CONTRACT_VERSION, (2, 5)); + assert_eq!(CONTRACT_VERSION, (2, 6)); assert_eq!(MAX_DOCKER_RUN_TIMEOUT_MS, 86_400_000); let serialized = serde_json::to_value(&request)?; assert_eq!(serialized["read_only_rootfs"], false); @@ -139,7 +139,7 @@ fn host_gateway_and_docker_facts_are_additive_and_default_safely() -> Result<(), #[test] fn version_and_capability_wire_snapshot_preserve_contract_compatibility() -> Result<(), serde_json::Error> { - assert_eq!(CONTRACT_VERSION, (2, 5)); + assert_eq!(CONTRACT_VERSION, (2, 6)); assert!(is_compatible(CONTRACT_VERSION)); assert!(!is_compatible((1, 21))); assert!(!is_compatible((1, 8))); @@ -158,7 +158,8 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility() assert!(!is_compatible((2, 2))); assert!(!is_compatible((2, 3))); assert!(!is_compatible((2, 4))); - assert!(is_compatible((2, 5))); + assert!(!is_compatible((2, 5))); + assert!(is_compatible((2, 6))); assert!(!supports_native_jail_resources((2, 0))); assert!(supports_native_jail_resources((2, 1))); assert!(supports_native_jail_resources((2, 2))); @@ -168,7 +169,7 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility() exec_backends: Vec::new(), spawn_backends: Vec::new(), }; - let snapshot = serde_json::json!({"contract_version":[2,5],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]}); + let snapshot = serde_json::json!({"contract_version":[2,6],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]}); assert_eq!(serde_json::to_value(&capabilities)?, snapshot); assert_eq!( serde_json::from_value::(snapshot)?, @@ -177,6 +178,30 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility() Ok(()) } +#[test] +fn disk_bytes_is_optional_and_absent_by_default() -> Result<(), serde_json::Error> { + // A 2.5 sender always set it; it still decodes, and re-encodes unchanged. + let older = serde_json::json!({ + "cpu_millis": 500, "memory_bytes": 1024, "pids_max": 8, "disk_bytes": 4096, + }); + let limits: ResourceLimits = serde_json::from_value(older.clone())?; + assert_eq!(limits.disk_bytes, Some(4096)); + assert_eq!(serde_json::to_value(limits)?, older); + + // Without one, nothing is claimed and nothing is sent. + let unset: ResourceLimits = serde_json::from_value(serde_json::json!({ + "cpu_millis": 500, "memory_bytes": 1024, "pids_max": 8, + }))?; + assert_eq!(unset.disk_bytes, None); + assert_eq!(ResourceLimits::default().disk_bytes, None); + assert!( + serde_json::to_value(ResourceLimits::default())? + .get("disk_bytes") + .is_none() + ); + Ok(()) +} + #[test] fn no_workspace_docker_operation_is_present_in_the_contract() { assert_eq!(METHODS.get(29), Some(&"RunDockerWithoutWorkspace")); @@ -187,7 +212,7 @@ fn no_workspace_docker_operation_is_present_in_the_contract() { .count(), 1 ); - assert_eq!(CONTRACT_VERSION, (2, 5)); + assert_eq!(CONTRACT_VERSION, (2, 6)); } #[test] @@ -200,7 +225,7 @@ fn shell_analysis_wire_shape_contains_only_structural_facts() -> Result<(), serd #[test] fn contract_two_drops_command_classification_but_keeps_structural_shell_analysis() { - assert_eq!(CONTRACT_VERSION, (2, 5)); + assert_eq!(CONTRACT_VERSION, (2, 6)); assert!(!METHODS.contains(&"AnalyzeCommand")); assert!(METHODS.contains(&"AnalyzeShell")); assert!(METHODS.contains(&"RunNativeShell")); diff --git a/crates/tinybox-module/src/tinybus_module/native_jail.rs b/crates/tinybox-module/src/tinybus_module/native_jail.rs index bfbbd597..076609e9 100644 --- a/crates/tinybox-module/src/tinybus_module/native_jail.rs +++ b/crates/tinybox-module/src/tinybus_module/native_jail.rs @@ -147,7 +147,11 @@ fn configure_resources(jail: &mut Jail, config: &NativeJailConfig) -> Result<()> cpu_millis: limits.cpu_millis, memory_bytes: limits.memory_bytes, pids_max: limits.pids_max, - disk_bytes: limits.disk_bytes, + // Required only when the caller set one; see + // `required_resource_constraints`. + disk_bytes: limits + .disk_bytes + .unwrap_or(tinybox_core::Resources::DEFAULT.disk_bytes), }); jail.hard_requirements .extend(required_resource_constraints(config.resources)); @@ -163,19 +167,20 @@ fn configure_resources(jail: &mut Jail, config: &NativeJailConfig) -> Result<()> fn required_resource_constraints( resources: Option, ) -> Vec { - if resources.is_some() { - // An explicitly supplied native jail budget is a hard request. The - // default values in a BoxSpec remain soft unless its own - // `hard_requirements` lists a constraint. - vec![ + // An explicitly supplied native jail budget is a hard request, disk + // included only when the caller set one. The default values in a BoxSpec + // remain soft unless its own `hard_requirements` lists a constraint. + resources.map_or_else(Vec::new, |limits| { + let mut constraints = vec![ tinybox_core::Constraint::Cpu, tinybox_core::Constraint::Memory, tinybox_core::Constraint::Pids, - tinybox_core::Constraint::Disk, - ] - } else { - Vec::new() - } + ]; + if limits.disk_bytes.is_some() { + constraints.push(tinybox_core::Constraint::Disk); + } + constraints + }) } /// Validate and canonicalize each existing absolute grant path. diff --git a/crates/tinybox-module/src/tinybus_module/native_jail_tests.rs b/crates/tinybox-module/src/tinybus_module/native_jail_tests.rs index 38a20174..e5e3a0de 100644 --- a/crates/tinybox-module/src/tinybus_module/native_jail_tests.rs +++ b/crates/tinybox-module/src/tinybus_module/native_jail_tests.rs @@ -203,7 +203,7 @@ fn requested_native_resource_limits_are_refused_before_spawn() cpu_millis: 500, memory_bytes: 1024 * 1024, pids_max: 32, - disk_bytes: 1024 * 1024, + disk_bytes: Some(1024 * 1024), }); // Declared enforcement accepts best-effort filesystem constraints, but a // resource budget remains a hard requirement and must refuse before spawn. @@ -211,6 +211,27 @@ fn requested_native_resource_limits_are_refused_before_spawn() Ok(()) } +#[test] +fn a_native_jail_budget_requires_disk_only_when_one_is_set() { + use tinybox_core::Constraint::{Cpu, Disk, Memory, Pids}; + let mut limits = tinybox_bus::ResourceLimits { + cpu_millis: 500, + memory_bytes: 1024 * 1024, + pids_max: 32, + disk_bytes: None, + }; + assert_eq!( + required_resource_constraints(Some(limits)), + vec![Cpu, Memory, Pids] + ); + limits.disk_bytes = Some(1024 * 1024); + assert_eq!( + required_resource_constraints(Some(limits)), + vec![Cpu, Memory, Pids, Disk] + ); + assert_eq!(required_resource_constraints(None), vec![]); +} + #[cfg(not(target_os = "linux"))] #[test] fn contract_21_resource_requests_refuse_before_spawn_on_non_linux() @@ -285,7 +306,7 @@ fn legacy_resource_limits_still_fail_closed_on_linux() cpu_millis: 100, memory_bytes: 64 * 1024 * 1024, pids_max: 16, - disk_bytes: 1024, + disk_bytes: Some(1024), }); assert!( diff --git a/crates/tinybox-module/src/tinybus_module/resources.rs b/crates/tinybox-module/src/tinybus_module/resources.rs index c806bfc8..5606d8f8 100644 --- a/crates/tinybox-module/src/tinybus_module/resources.rs +++ b/crates/tinybox-module/src/tinybus_module/resources.rs @@ -1687,7 +1687,12 @@ fn make_spec(request: &CreateRequest, host: &str) -> Result { cpu_millis: request.resources.cpu_millis, memory_bytes: request.resources.memory_bytes, pids_max: request.resources.pids_max, - disk_bytes: request.resources.disk_bytes, + // A box's resources are soft unless listed as hard requirements, and + // nothing applies a disk budget; keep the core default when unset. + disk_bytes: request + .resources + .disk_bytes + .unwrap_or(tinybox_core::Resources::DEFAULT.disk_bytes), }; spec.ports .extend(request.ports.iter().map(|port| tinybox_core::PortMapping { diff --git a/crates/tinybox-module/src/tinybus_module/resources_tests.rs b/crates/tinybox-module/src/tinybus_module/resources_tests.rs index 410ab21c..ec45990e 100644 --- a/crates/tinybox-module/src/tinybus_module/resources_tests.rs +++ b/crates/tinybox-module/src/tinybus_module/resources_tests.rs @@ -63,7 +63,7 @@ fn sandbox_selection_and_spec_mapping_preserve_host_policy() -> Result<()> { cpu_millis: 1500, memory_bytes: 1_000_000, pids_max: 12, - disk_bytes: 2_000_000, + disk_bytes: Some(2_000_000), }, ports: vec![tinybox_bus::PortMapping { guest: 8080, @@ -86,6 +86,25 @@ fn sandbox_selection_and_spec_mapping_preserve_host_policy() -> Result<()> { Ok(()) } +#[test] +fn an_unset_disk_budget_keeps_the_soft_core_default() -> Result<()> { + let request = CreateRequest { + resource: ResourceId("disk-test".into()), + backend: "docker".into(), + workspace: Workspace::Directory("/work".into()), + ..Default::default() + }; + assert_eq!(request.resources.disk_bytes, None); + let spec = make_spec(&request, "local")?; + assert_eq!( + spec.resources.disk_bytes, + tinybox_core::Resources::DEFAULT.disk_bytes + ); + // Soft: nothing asks a backend to enforce it. + assert_eq!(spec.hard_requirements, vec![]); + Ok(()) +} + #[test] fn spec_mapping_carries_retention_into_the_box_spec() -> Result<()> { let request = CreateRequest { diff --git a/docs/specs/contract-2-6.md b/docs/specs/contract-2-6.md new file mode 100644 index 00000000..ac497186 --- /dev/null +++ b/docs/specs/contract-2-6.md @@ -0,0 +1,23 @@ +# TinyBox contract 2.6 + +Contract 2.6 makes one field optional, without changing any other 2.5 request +or reply shape: + +| Change | What a host may rely on | +| --- | --- | +| `ResourceLimits.disk_bytes` | `Option`, `None` by default, omitted on the wire when `None`. A value sent by an older host still decodes as `Some`. | + +No backend enforces a writable disk budget, so the 8 GiB default was a number +nothing applied: + +- On `Create`, a box's resources stay soft unless the caller lists them as + hard requirements, and an unset `disk_bytes` keeps the core default + (`Resources::DEFAULT`). +- On a native jail, `NativeJailConfig.resources` remains a hard request for + CPU, memory and pids, and asks for `Disk` only when `disk_bytes` is set. + Before 2.6 every such request carried a disk budget and was refused by every + backend; without one it now reaches backends able to hold the other three. + +A 2.6 host refuses a 2.5 module, as for every minor. That matters here: a +module before 2.6 fails to decode a `ResourceLimits` without `disk_bytes`, so a +host must have bound a 2.6 module before it sends one.