Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
refactor(cua-image): move the build, sidecar and default-image helpers out of cua-fleet (CUA-1834) (#5442)
Francesco Bonacci878d80f679e8
diff --git a/docs/content/docs/cua-sdk/reference/rust/cua-fleet.mdx b/docs/content/docs/cua-sdk/reference/rust/cua-fleet.mdxindex 2264cce6fa..54a778ed7e 100644--- a/docs/content/docs/cua-sdk/reference/rust/cua-fleet.mdx+++ b/docs/content/docs/cua-sdk/reference/rust/cua-fleet.mdx@@ -115,36 +115,6 @@ impl BillingStatus {}```-### `BuildFile`--A local file copied into the image.--```rust-pub struct BuildFile {- pub source: PathBuf,- pub destination: String,-}-```--### `BuildSpec`--What to build.--```rust-pub struct BuildSpec {- pub from: String,- pub layers: Vec<ImageLayer>,- pub env: BTreeMap<String, String>,- pub ports: Vec<u16>,- pub files: Vec<BuildFile>,- pub timeout: Option<Duration>,-}-impl BuildSpec {- fn is_empty(&self) -> bool;- fn validate(&self) -> Result<()>;-}-```-### `BuiltImage`A built (or cached) image.@@ -633,26 +603,6 @@ impl SandboxSpec {}```-### `Sidecar`--An extra container next to a sandbox.--```rust-pub struct Sidecar {- pub name: String,- pub image: String,- pub command: Option<Vec<String>>,- pub env: BTreeMap<String, String>,- pub ports: Vec<u16>,- pub args: Option<Vec<String>>,- pub cpu: Option<String>,- pub memory: Option<String>,-}-impl Sidecar {- fn new(image: impl Into<String>) -> Self;-}-```-### `SpecDiff`One field where a pool's template differs from the ...@@ -728,14 +678,10 @@ pub fn canonical_image(os: &str) -> Stringpub fn check_cloud_size(cpu: Option<u32>, memory_mb: Option<u32>) -> Result<()>/// Checks a pool size field (`what` ...pub fn check_pool_size(what: &str, n: u32) -> Result<()>-/// Refuses `RESERVED_SERVICE_NAMES` in ...-pub fn check_reserved_service_names<'a>(services: impl IntoIterator<Item = &'a String>, has_sidecars: bool) -> Result<()>/// Validates the runtime/image pairing ...pub fn check_runtime(runtime: Option<RuntimeKind>, image: &str, evidence: &ImageEvidence) -> Result<RuntimeKind>/// Forgets cached rates (sign-out, tests).pub fn clear_pricing_cache()-/// redis for docker. ...-pub fn default_sidecar_name(image: &str) -> String/// Refuses a runtime this SDK does not ...pub fn ensure_runtime_offered(runtime: &RuntimeKind) -> Result<()>/// Name of an ephemeral pool: cua-eph-<12 ...@@ -768,8 +714,6 @@ pub fn sdk_error_is_not_found(e: &SdkError) -> boolpub fn set_image_inspector(inspector: Option<Arc<dyn ImageInspector>>)/// A `fleets_pool` resource block (the ...pub fn terraform_pool_block(name: &str, spec: &SandboxSpec, options: &PoolOptions, runtime: &RuntimeKind) -> String-/// Checks sidecars the way Fleet's ...-pub fn validate_sidecars(sidecars: &[Sidecar], reserved: &[u16]) -> Result<()>// mod autopool/// The base pool name for a tenant and ...@@ -782,14 +726,8 @@ pub fn default_cua_home() -> PathBufpub fn tenant_from_token(token: &str) -> String// mod builds-/// The content-addressed Image name for a ...-pub fn build_name(recipe: &ImageRecipe) -> String/// The build namespace for a tenant ...pub fn build_namespace(tenant: &str) -> String-/// The recipe a build of `spec` on `base` ...-pub fn build_recipe(spec: &BuildSpec, base: &str, files: Vec<ImageFile>, from_pull_secret: Option<String>) -> ImageRecipe-/// A local build's content-addressed ...-pub fn local_build_file(f: &BuildFile) -> Result<ImageFile>// mod claim_secrets/// The Opaque Secret the SDK writes for ...@@ -841,10 +779,6 @@ pub const FLEET_ABSOLUTE_MAX_POOL_SIZE: u32 = 50;pub const FLEET_ABSOLUTE_MEMORY_MB: RangeInclusive<u32> = _;/// Why a macOS image or the `macos` ...pub const MACOS_UNSUPPORTED: &str = cua_image::resolve::FLEET_MACOS_UNSUPPORTED;-/// The hostname sidecars reach the sandbox ...-pub const MAIN_CONTAINER_NAME: &str = "main";-/// Most sidecars a template may carry ...-pub const MAX_SIDECARS: usize = 8;/// The one "no Fleet credentials" message ...pub const MISSING_CREDENTIALS: &str = "Fleet credentials missing: run `cua auth login` or set \CUA_CLIENT_ID/CUA_CLIENT_SECRET, or pass local=True";@@ -854,8 +788,6 @@ pub const PRICING_TTL: Duration = _;pub const REGISTRY_SECRET_PREFIX: &str = "cua-registry-";/// Whether Fleet builds `kind: container` ...pub const REMOTE_BUILDS_SUPPORTED: bool = false;-/// Service names a sandbox with sidecars ...-pub const RESERVED_SERVICE_NAMES: [&str; 3] = _;// mod autopool/// Name prefix of managed pools.@@ -880,16 +812,8 @@ pub const MIN_BIND_DEADLINE_SECS: u64 = 900;pub const SPEC_HASH_LABEL_LEN: usize = 32;// mod builds-/// Prefix of content-named Image resources.-pub const BUILD_NAME_PREFIX: &str = "cua-b-";/// Prefix of the per-account build ...pub const BUILD_NAMESPACE_PREFIX: &str = "cua-build-";-/// Default build budget.-pub const DEFAULT_BUILD_TIMEOUT: Duration = _;-/// Most environment variables a remote ...-pub const MAX_BUILD_ENV: usize = 128;-/// Longest environment value a remote ...-pub const MAX_BUILD_ENV_VALUE: usize = 8192;/// Largest file `copy` uploads (read into ...pub const MAX_COPY_BYTES: u64 = _;@@ -933,4 +857,4 @@ pub type BuildProgress<'a> = &'a dyn Fn(&str) + Send + Sync;## Re-exports-`cyclops_sdk::Sandbox`, `cyclops_sdk::Claim`, `cyclops_sdk::HttpClient`, `cua_image::spec::ImageLayer`, `cua_image::normalize_registry`, `cua_image::RegistryCredentials`, `cyclops_sdk::Pool`, `cua_image::registry_of`, `parity::RegistryCredentials`, `pool::RuntimeKind`, `cyclops_sdk_schema`, `cyclops_sdk`, `cyclops_sdk::SdkError`, `cyclops_sdk::Template`.+`cyclops_sdk::Sandbox`, `cua_image::build::BuildFile`, `cua_image::build::build_name`, `cua_image::build::BUILD_NAME_PREFIX`, `cua_image::build::build_recipe`, `cua_image::build::BuildFile`, `cua_image::build::BuildSpec`, `cua_image::build::DEFAULT_BUILD_TIMEOUT`, `cua_image::build::local_build_file`, `cua_image::build::MAX_BUILD_ENV`, `cua_image::build::MAX_BUILD_ENV_VALUE`, `cua_image::build::BuildSpec`, `cua_image::sidecar::check_reserved_service_names`, `cyclops_sdk::Claim`, `cua_image::sidecar::default_sidecar_name`, `cyclops_sdk::HttpClient`, `cua_image::spec::ImageLayer`, `cua_image::sidecar::MAIN_CONTAINER_NAME`, `cua_image::sidecar::MAX_SIDECARS`, `cua_image::normalize_registry`, `cua_image::RegistryCredentials`, `cyclops_sdk::Pool`, `cua_image::registry_of`, `parity::RegistryCredentials`, `cua_image::sidecar::RESERVED_SERVICE_NAMES`, `pool::RuntimeKind`, `cyclops_sdk_schema`, `cyclops_sdk`, `cyclops_sdk::SdkError`, `cua_image::sidecar::Sidecar`, `cyclops_sdk::Template`, `cua_image::sidecar::validate_sidecars`.diff --git a/libs/cua/crates/cua-fleet/examples/fleet-docs-dump.rs b/libs/cua/crates/cua-fleet/examples/fleet-docs-dump.rsindex 56770adac5..197223b464 100644--- a/libs/cua/crates/cua-fleet/examples/fleet-docs-dump.rs+++ b/libs/cua/crates/cua-fleet/examples/fleet-docs-dump.rs@@ -63,7 +63,7 @@ fn main() {"object": "Template","field": "spec.vmTemplate.sidecars","type": "object[]",- "description": format!("Containers that run next to the sandbox, on every runtime (at most {}). They reach the sandbox at host `{}`.", parity::MAX_SIDECARS, parity::MAIN_CONTAINER_NAME),+ "description": format!("Containers that run next to the sandbox, on every runtime (at most {}). They reach the sandbox at host `{}`.", cua_fleet::MAX_SIDECARS, cua_fleet::MAIN_CONTAINER_NAME),},{"object": "Template",@@ -125,7 +125,7 @@ fn main() {},"registry": {"prefix": parity::REGISTRY_SECRET_PREFIX,- "max_sidecars": parity::MAX_SIDECARS,+ "max_sidecars": cua_fleet::MAX_SIDECARS,"example": registry_body,},},diff --git a/libs/cua/crates/cua-fleet/src/builds.rs b/libs/cua/crates/cua-fleet/src/builds.rsindex 6bd4e3816a..d75bda8f60 100644--- a/libs/cua/crates/cua-fleet/src/builds.rs+++ b/libs/cua/crates/cua-fleet/src/builds.rs@@ -12,121 +12,28 @@//! in a pool namespace (pools are keyed by the image a build produces).use crate::{Error, FleetClient, RegistryCredentials, Result, parity};-use cua_image::spec::{- ImageFile, ImageFileReference, ImageLayer, ImageRecipe, ImageResource, RecipeKind,-};-use serde_json::{Value, json};+use cua_image::spec::{ImageFile, ImageFileReference, ImageResource};+use serde_json::Value;use sha2::{Digest, Sha256};use std::{- collections::{BTreeMap, HashMap},- path::PathBuf,+ collections::HashMap,sync::{Mutex, OnceLock},time::{Duration, Instant},};+// The build spec and the content-addressed names and recipes are not Fleet's:+// they live in `cua-image` (`cua_image::build`), where local builds use them+// too. Re-exported here so every `cua_fleet::builds::*` path still resolves.+pub use cua_image::build::{+ BUILD_NAME_PREFIX, BuildFile, BuildSpec, DEFAULT_BUILD_TIMEOUT, MAX_BUILD_ENV,+ MAX_BUILD_ENV_VALUE, build_name, build_recipe, local_build_file,+};+/// Prefix of the per-account build namespace.pub const BUILD_NAMESPACE_PREFIX: &str = "cua-build-";-/// Prefix of content-named Image resources.-pub const BUILD_NAME_PREFIX: &str = "cua-b-";-/// Default build budget.-pub const DEFAULT_BUILD_TIMEOUT: Duration = Duration::from_secs(3600);-/// Most environment variables a remote build takes (the rootfs builder's-/// limit, trycua/cloud#7887).-pub const MAX_BUILD_ENV: usize = 128;-/// Longest environment value a remote build takes.-pub const MAX_BUILD_ENV_VALUE: usize = 8192;/// Largest file `copy` uploads (read into memory once).pub const MAX_COPY_BYTES: u64 = 64 << 20;-/// What to build.-#[derive(Clone, Debug, Default, PartialEq, Eq)]-pub struct BuildSpec {- /// Registry base image.- pub from: String,- /// Build steps, in order.- pub layers: Vec<ImageLayer>,- /// Image environment.- pub env: BTreeMap<String, String>,- /// Ports the image exposes.- pub ports: Vec<u16>,- /// Local files copied into the image.- pub files: Vec<BuildFile>,- /// Build budget (default one hour).- pub timeout: Option<Duration>,-}--/// A local file copied into the image.-#[derive(Clone, Debug, PartialEq, Eq)]-pub struct BuildFile {- /// Local path.- pub source: PathBuf,- /// Absolute path in the image.- pub destination: String,-}--impl BuildSpec {- /// Whether there is anything to build on top of `from`.- pub fn is_empty(&self) -> bool {- self.layers.is_empty() && self.env.is_empty() && self.files.is_empty()- }-- /// Checks the spec (a base, no VM-only layers, env names, absolute- /// copy destinations).- pub fn validate(&self) -> Result<()> {- if self.from.trim().is_empty() || self.from.chars().any(char::is_whitespace) {- return Err(Error::InvalidArgument(- "a remote build needs a base image reference".into(),- ));- }- if self- .layers- .iter()- .any(|l| matches!(l, ImageLayer::AppInstall { .. }))- {- return Err(Error::InvalidArgument(- "app_install layers need a VM image; a cloud build on a registry base makes a \- container image"- .into(),- ));- }- if let Some(k) = self.env.keys().find(|k| !cua_image::spec::is_env_name(k)) {- return Err(Error::InvalidArgument(format!(- "bad environment variable name {k:?}"- )));- }- // The rootfs builder writes each value as one Dockerfile ENV line- // and refuses anything else; say so before uploading anything.- if self.env.len() > MAX_BUILD_ENV {- return Err(Error::InvalidArgument(format!(- "a remote build takes at most {MAX_BUILD_ENV} environment variables (got {})",- self.env.len()- )));- }- for (k, v) in &self.env {- if v.contains('\n') || v.contains('\r') {- return Err(Error::InvalidArgument(format!(- "environment variable {k} has a multi-line value; a remote build stores \- each value as one line (encode it, or set it at runtime with env=)"- )));- }- if v.len() > MAX_BUILD_ENV_VALUE {- return Err(Error::InvalidArgument(format!(- "environment variable {k} is longer than {MAX_BUILD_ENV_VALUE} bytes"- )));- }- }- for f in &self.files {- if !f.destination.starts_with('/') {- return Err(Error::InvalidArgument(format!(- "copy destination {:?} must be an absolute path",- f.destination- )));- }- }- Ok(())- }-}-/// A built (or cached) image.#[derive(Clone, Debug, PartialEq, Eq)]pub struct BuiltImage {@@ -155,86 +62,6 @@ pub fn build_namespace(tenant: &str) -> String {)}-/// The content-addressed Image name for a recipe.-pub fn build_name(recipe: &ImageRecipe) -> String {- let canonical = serde_json::to_string(&json!({- "domain": "cua.remote-build/v1",- "recipe": recipe,- }))- .unwrap_or_default();- format!(- "{BUILD_NAME_PREFIX}{}",- &hex::encode(Sha256::digest(canonical.as_bytes()))[..24]- )-}--/// The recipe a build of `spec` on `base` (pinned by digest) makes. Remote-/// builds (with uploaded `files`) and local builds (with-/// [`local_build_file`] references) are named by the same-/// [`build_name`] of it, so an identical spec is one content hash.-pub fn build_recipe(- spec: &BuildSpec,- base: &str,- files: Vec<ImageFile>,- from_pull_secret: Option<String>,-) -> ImageRecipe {- ImageRecipe {- distro: "registry".into(),- version: version_of(&spec.from),- kind: RecipeKind::Container,- from: Some(base.to_string()),- from_pull_secret,- layers: spec.layers.clone(),- env: spec.env.clone(),- files,- ports: {- let mut p = spec.ports.clone();- p.sort_unstable();- p.dedup();- p- },- ..Default::default()- }-}--/// A local build's content-addressed reference for a `copy` file (the-/// same shape as an upload: its sha256 and size), for [`build_recipe`].-pub fn local_build_file(f: &BuildFile) -> Result<ImageFile> {- let meta = std::fs::metadata(&f.source)- .map_err(|e| Error::InvalidArgument(format!("copy {}: {e}", f.source.display())))?;- if !meta.is_file() {- return Err(Error::InvalidArgument(format!(- "copy {}: builds copy single files",- f.source.display()- )));- }- let bytes = std::fs::read(&f.source)- .map_err(|e| Error::InvalidArgument(format!("copy {}: {e}", f.source.display())))?;- let digest = hex::encode(Sha256::digest(&bytes));- Ok(ImageFile {- source: ImageFileReference {- reference: format!("uploads/local/{}", &digest[..32]),- digest: format!("sha256:{digest}"),- size_bytes: meta.len(),- },- destination: f.destination.clone(),- })-}--/// The tag of `reference` as a recipe `version` (1..64 chars), or `latest`.-fn version_of(reference: &str) -> String {- let no_digest = reference.split('@').next().unwrap_or(reference);- let tag = match no_digest.rsplit_once(':') {- Some((_, t)) if !t.contains('/') => t,- _ => "latest",- };- let mut v: String = tag.chars().take(64).collect();- if v.is_empty() {- v = "latest".into();- }- v-}-fn memo() -> &'static Mutex<HashMap<String, BuiltImage>> {static M: OnceLock<Mutex<HashMap<String, BuiltImage>>> = OnceLock::new();M.get_or_init(Default::default)@@ -465,68 +292,18 @@ impl FleetClient {#[cfg(test)]mod tests {use super::*;+ use cua_image::spec::ImageRecipe;#[test]- fn local_builds_share_the_content_hash() {- let dir = tempfile::tempdir().unwrap();- let path = dir.path().join("app.py");- std::fs::write(&path, b"print(1)\n").unwrap();- let spec = BuildSpec {- from: "python:3.12-slim".into(),- layers: vec![ImageLayer::PipInstall {- packages: vec!["mcp".into()],- }],- files: vec![BuildFile {- source: path.clone(),- destination: "/srv/app.py".into(),- }],- ports: vec![8000, 8000],- ..Default::default()- };- let base = "docker.io/library/python@sha256:ab";- let name = |spec: &BuildSpec| {- let files = spec- .files- .iter()- .map(|f| local_build_file(f).unwrap())- .collect();- build_name(&build_recipe(spec, base, files, None))- };- let first = name(&spec);- assert!(first.starts_with(BUILD_NAME_PREFIX) && first.len() == 6 + 24);- assert_eq!(name(&spec.clone()), first, "same spec, same name");- // File content is part of the hash; its path is not.- std::fs::write(&path, b"print(2)\n").unwrap();- assert_ne!(name(&spec), first);- let f = local_build_file(&spec.files[0]).unwrap();- assert!(f.source.digest.starts_with("sha256:"));- assert_eq!(f.source.size_bytes, 9);- assert!(- local_build_file(&BuildFile {- source: dir.path().into(),- destination: "/x".into()- })- .is_err()- );- }-- #[test]- fn names_are_content_addressed() {- let r = |cmd: &str| ImageRecipe {+ fn namespaces_and_names_are_dns_labels() {+ let name = build_name(&ImageRecipe {distro: "registry".into(),version: "3.12-slim".into(),- kind: RecipeKind::Container,from: Some("docker.io/library/python@sha256:ab".into()),- layers: vec![ImageLayer::Run {- command: cmd.into(),- }],..Default::default()- };- assert_eq!(build_name(&r("true")), build_name(&r("true")));- assert_ne!(build_name(&r("true")), build_name(&r("false")));- let n = build_name(&r("true"));- assert!(n.starts_with("cua-b-") && n.len() == 6 + 24);- assert!(cyclops_sdk::validate_dns_label(&n).is_ok());+ });+ assert!(name.starts_with(BUILD_NAME_PREFIX));+ assert!(cyclops_sdk::validate_dns_label(&name).is_ok());let ns = build_namespace("tenant-a");assert!(ns.starts_with("cua-build-") && cyclops_sdk::validate_dns_label(&ns).is_ok());assert_ne!(ns, build_namespace("tenant-b"));@@ -537,10 +314,7 @@ mod tests {}#[test]- fn versions_and_pins() {- assert_eq!(version_of("python:3.12-slim"), "3.12-slim");- assert_eq!(version_of("localhost:5000/app"), "latest");- assert_eq!(version_of("r.io/a@sha256:ab"), "latest");+ fn pins() {assert_eq!(pinned("reg.test/builds/x:rootfs-1", "sha256:cd"),"reg.test/builds/x@sha256:cd"@@ -552,56 +326,13 @@ mod tests {}#[test]- fn specs_validate() {- let ok = BuildSpec {- from: "python:3.12-slim".into(),- layers: vec![ImageLayer::PipInstall {- packages: vec!["mcp".into()],- }],- ..Default::default()- };- ok.validate().unwrap();- assert!(!ok.is_empty());- let app = BuildSpec {- layers: vec![ImageLayer::AppInstall { app_id: "x".into() }],- ..ok.clone()- };- assert!(app.validate().is_err());- let rel = BuildSpec {- files: vec![BuildFile {- source: "a".into(),- destination: "rel".into(),- }],- ..ok.clone()- };- assert!(rel.validate().is_err());- let multi = BuildSpec {- env: [("CERT".to_string(), "line1\nline2".to_string())].into(),- ..ok.clone()- };- let e = multi.validate().unwrap_err().to_string();- assert!(e.contains("multi-line") && e.contains("CERT"), "{e}");- let cr = BuildSpec {- env: [("A".to_string(), "x\ry".to_string())].into(),- ..ok.clone()- };- assert!(cr.validate().is_err());- let long = BuildSpec {- env: [("A".to_string(), "x".repeat(MAX_BUILD_ENV_VALUE + 1))].into(),- ..ok.clone()- };- assert!(long.validate().is_err());- let many = BuildSpec {- env: (0..=MAX_BUILD_ENV)- .map(|i| (format!("V{i}"), "1".to_string()))- .collect(),- ..ok.clone()- };- assert!(many.validate().is_err());- let single = BuildSpec {- env: [("A".to_string(), "one line with spaces $X".to_string())].into(),- ..ok- };- single.validate().unwrap();+ fn a_refused_spec_is_an_invalid_argument() {+ // `BuildSpec::validate` lives in cua-image; its error becomes the+ // crate's `Error::InvalidArgument` with the same message.+ let e: Error = BuildSpec::default().validate().unwrap_err().into();+ assert!(+ matches!(&e, Error::InvalidArgument(m) if m.contains("base image")),+ "{e:?}"+ );}}diff --git a/libs/cua/crates/cua-fleet/src/lib.rs b/libs/cua/crates/cua-fleet/src/lib.rsindex 247024d9b6..a2c5c712a1 100644--- a/libs/cua/crates/cua-fleet/src/lib.rs+++ b/libs/cua/crates/cua-fleet/src/lib.rs@@ -48,8 +48,13 @@ pub use cyclops_sdk_schema as schema;pub const MISSING_CREDENTIALS: &str = "Fleet credentials missing: run `cua auth login` or set \CUA_CLIENT_ID/CUA_CLIENT_SECRET, or pass local=True";pub use billing::{BillingCard, BillingCredit, BillingStatus};-pub use builds::{BuildFile, BuildSpec, BuiltImage};+pub use builds::BuiltImage;pub use claim_secrets::{ClaimSecretsWait, TokenProbe, TokenState};+pub use cua_image::build::{BuildFile, BuildSpec};+pub use cua_image::sidecar::{+ MAIN_CONTAINER_NAME, MAX_SIDECARS, RESERVED_SERVICE_NAMES, Sidecar,+ check_reserved_service_names, default_sidecar_name, validate_sidecars,+};pub use cua_image::spec::ImageLayer;pub use cua_image::{normalize_registry, registry_of};pub use limits::{@@ -58,9 +63,8 @@ pub use limits::{};pub(crate) use parity::sidecars_json;pub use parity::{- MAIN_CONTAINER_NAME, MAX_SIDECARS, REGISTRY_SECRET_PREFIX, REMOTE_BUILDS_SUPPORTED,- RESERVED_SERVICE_NAMES, RegistryCredentials, Sidecar, check_reserved_service_names,- default_sidecar_name, registry_secret_name, remote_builds_unsupported, validate_sidecars,+ REGISTRY_SECRET_PREFIX, REMOTE_BUILDS_SUPPORTED, RegistryCredentials, registry_secret_name,+ remote_builds_unsupported,};pub use pool::{ClaimOptions, PoolHandle, PoolSpec, RuntimeKind, ephemeral_pool_name};pub use pricing::{PRICING_TTL, UsagePricing, clear_pricing_cache};@@ -202,6 +206,13 @@ impl Error {}}+impl From<cua_image::InvalidArgument> for Error {+ /// A value `cua-image`'s build or sidecar rules refuse (the same message).+ fn from(e: cua_image::InvalidArgument) -> Self {+ Error::InvalidArgument(e.0)+ }+}+impl From<SdkError> for Error {/// A Fleet admission refusal becomes [`Error::AdmissionDenied`] with/// Fleet's message (never the pool-name hint ofdiff --git a/libs/cua/crates/cua-fleet/src/parity.rs b/libs/cua/crates/cua-fleet/src/parity.rsindex 20a777b6ed..100f771505 100644--- a/libs/cua/crates/cua-fleet/src/parity.rs+++ b/libs/cua/crates/cua-fleet/src/parity.rs@@ -8,19 +8,21 @@//!//! Sidecars are addressed by name on every runtime: the sandbox reaches a//! sidecar at its name (on its declared ports) and a sidecar reaches the-//! sandbox at [`MAIN_CONTAINER_NAME`]. Pod runtimes (gVisor) run them in the-//! sandbox pod (so `localhost` works too); KubeVirt runs them in a companion-//! gVisor pod and names them in the guest's `/etc/hosts` through cloud-init.+//! sandbox at [`cua_image::sidecar::MAIN_CONTAINER_NAME`]. Pod runtimes+//! (gVisor) run them in the sandbox pod (so `localhost` works too); KubeVirt+//! runs them in a companion gVisor pod and names them in the guest's+//! `/etc/hosts` through cloud-init.use crate::{Error, FleetClient, Result};use base64::Engine as _;use cyclops_sdk::{HttpHeader, HttpRequest, SdkError};-use serde::{Deserialize, Serialize};use serde_json::{Value, json};use sha2::{Digest, Sha256};-use std::collections::BTreeMap;pub use cua_image::RegistryCredentials;+// The sidecar type and its rules are not Fleet's: they live in `cua-image`+// (`cua_image::sidecar`) and apply to every provider.+use cua_image::sidecar::Sidecar;/// Whether Fleet builds `kind: container` image recipes (remote builds of/// `Image` layers on a registry base). Off until Fleet's builder runs them.@@ -30,18 +32,6 @@ pub const REMOTE_BUILDS_SUPPORTED: bool = cfg!(feature = "fleet-remote-builds");/// in #7887).pub const REGISTRY_SECRET_PREFIX: &str = "cua-registry-";-/// Most sidecars a template may carry (Fleet's admission limit).-pub const MAX_SIDECARS: usize = 8;--/// The hostname sidecars reach the sandbox at, and a name no sidecar may-/// take.-pub const MAIN_CONTAINER_NAME: &str = "main";--/// Service names a sandbox with sidecars may not use (Fleet's KubeVirt-/// companion names its own Services with them; reserved on every runtime,-/// locally too, so a spec stays portable).-pub const RESERVED_SERVICE_NAMES: [&str; 3] = ["main", "sidecars", "sc"];-/// The error for a remote image build Fleet cannot run yet.pub fn remote_builds_unsupported(what: &str) -> Error {Error::InvalidArgument(format!(@@ -50,166 +40,6 @@ pub fn remote_builds_unsupported(what: &str) -> Error {))}-/// Refuses [`RESERVED_SERVICE_NAMES`] in `services` when `sidecars` is-/// non-empty (Fleet's admission rule; a sandbox without sidecars may use-/// them).-pub fn check_reserved_service_names<'a>(- services: impl IntoIterator<Item = &'a String>,- has_sidecars: bool,-) -> Result<()> {- if !has_sidecars {- return Ok(());- }- if let Some(n) = services- .into_iter()- .find(|n| RESERVED_SERVICE_NAMES.contains(&n.as_str()))- {- return Err(Error::InvalidArgument(format!(- "service name {n:?} is reserved in a sandbox with sidecars (reserved: {})",- RESERVED_SERVICE_NAMES.join(", ")- )));- }- Ok(())-}--/// An extra container next to a sandbox. The sandbox reaches it at its-/// `name` as a hostname (on its declared `ports`), and it reaches the-/// sandbox at [`MAIN_CONTAINER_NAME`]. Local containers and gVisor pods-/// share one network namespace, so `localhost` works there too.-#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]-pub struct Sidecar {- /// Name, unique within the sandbox (DNS label, not `main`); also its- /// hostname.- pub name: String,- /// Image reference.- pub image: String,- /// argv replacing the image's ENTRYPOINT.- #[serde(default, skip_serializing_if = "Option::is_none")]- pub command: Option<Vec<String>>,- /// Environment (plain values, not secrets).- #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]- pub env: BTreeMap<String, String>,- /// Ports it listens on.- #[serde(default, skip_serializing_if = "Vec::is_empty")]- pub ports: Vec<u16>,- /// Arguments after `command` (or the image's entrypoint).- #[serde(default, skip_serializing_if = "Option::is_none")]- pub args: Option<Vec<String>>,- /// CPU request as a Kubernetes quantity (`500m`, `1`). Cloud only.- #[serde(default, skip_serializing_if = "Option::is_none")]- pub cpu: Option<String>,- /// Memory request as a Kubernetes quantity (`256Mi`). Cloud only.- #[serde(default, skip_serializing_if = "Option::is_none")]- pub memory: Option<String>,-}--impl Sidecar {- /// A sidecar running `image`, named after the image's repository.- pub fn new(image: impl Into<String>) -> Self {- let image = image.into();- Self {- name: default_sidecar_name(&image),- image,- command: None,- env: BTreeMap::new(),- ports: vec![],- args: None,- cpu: None,- memory: None,- }- }-}--/// `redis` for `docker.io/library/redis:7-alpine`: the last path segment of-/// the repository, lowercased to a DNS label.-pub fn default_sidecar_name(image: &str) -> String {- let repo = image.split('@').next().unwrap_or(image);- let last = repo.rsplit('/').next().unwrap_or(repo);- let last = last.split(':').next().unwrap_or(last);- let mut name: String = last- .chars()- .map(|c| {- if c.is_ascii_alphanumeric() {- c.to_ascii_lowercase()- } else {- '-'- }- })- .collect();- name = name.trim_matches('-').to_string();- name.truncate(50);- let name = name.trim_end_matches('-').to_string();- if name.is_empty() || name == "main" {- "sidecar".into()- } else {- name- }-}--/// Checks sidecars the way Fleet's admission does (so a bad spec fails-/// before any pool exists): at most [`MAX_SIDECARS`], unique DNS-label names-/// other than `main`, an image each, valid env names, ports in range and-/// not claimed by two sidecars. `reserved` ports belong to the sandbox-/// itself (its spacesd); services may target sidecar ports.-pub fn validate_sidecars(sidecars: &[Sidecar], reserved: &[u16]) -> Result<()> {- if sidecars.len() > MAX_SIDECARS {- return Err(Error::InvalidArgument(format!(- "at most {MAX_SIDECARS} sidecars (got {})",- sidecars.len()- )));- }- let mut names = std::collections::BTreeSet::new();- let mut ports: BTreeMap<u16, String> = BTreeMap::new();- for s in sidecars {- if cyclops_sdk::validate_dns_label(&s.name).is_err() || s.name == MAIN_CONTAINER_NAME {- return Err(Error::InvalidArgument(format!(- "sidecar name {:?} must be a DNS label other than \"main\"",- s.name- )));- }- if !names.insert(s.name.as_str()) {- return Err(Error::InvalidArgument(format!(- "sidecar name {:?} is used twice",- s.name- )));- }- if s.image.trim().is_empty() {- return Err(Error::InvalidArgument(format!(- "sidecar {:?} needs an image",- s.name- )));- }- if let Some(k) = s.env.keys().find(|k| !cua_image::spec::is_env_name(k)) {- return Err(Error::InvalidArgument(format!(- "sidecar {:?}: bad environment variable name {k:?}",- s.name- )));- }- for p in &s.ports {- if *p == 0 {- return Err(Error::InvalidArgument(format!(- "sidecar {:?}: port 0",- s.name- )));- }- if reserved.contains(p) {- return Err(Error::InvalidArgument(format!(- "sidecar {:?} port {p} is also a sandbox port (containers share one \- network namespace)",- s.name- )));- }- if let Some(other) = ports.insert(*p, s.name.clone()) {- return Err(Error::InvalidArgument(format!(- "port {p} is claimed by sidecars {other:?} and {:?}",- s.name- )));- }- }- }- Ok(())-}-/// `vmTemplate.sidecars[]` entries (`SandboxSidecar`). CPU and memory are/// left to Fleet's defaults (500m / 512Mi) unless set; local sidecars use/// the same defaults.@@ -492,60 +322,6 @@ fn secret_status(op: &str, name: &str, status: u16) -> Error {mod tests {use super::*;- #[test]- fn default_names_are_dns_labels() {- assert_eq!(default_sidecar_name("redis:7-alpine"), "redis");- assert_eq!(- default_sidecar_name("docker.io/library/postgres@sha256:ab"),- "postgres"- );- assert_eq!(default_sidecar_name("ghcr.io/me/My_Svc:1"), "my-svc");- assert_eq!(default_sidecar_name("reg:5000/main"), "sidecar");- }-- #[test]- fn sidecars_validate_like_admission() {- let db = Sidecar {- ports: vec![6379],- ..Sidecar::new("redis:7-alpine")- };- validate_sidecars(std::slice::from_ref(&db), &[8000]).unwrap();- assert!(- validate_sidecars(&[db.clone(), db.clone()], &[]).is_err(),- "dup name"- );- assert!(- validate_sidecars(std::slice::from_ref(&db), &[6379]).is_err(),- "port clash"- );- let twin = Sidecar {- name: "db2".into(),- ..db.clone()- };- assert!(- validate_sidecars(&[db.clone(), twin], &[]).is_err(),- "shared port"- );- let main = Sidecar {- name: "main".into(),- ..db.clone()- };- assert!(validate_sidecars(&[main], &[]).is_err());- let many: Vec<Sidecar> = (0..9)- .map(|i| Sidecar {- name: format!("s{i}"),- ports: vec![],- ..db.clone()- })- .collect();- assert!(validate_sidecars(&many, &[]).is_err());- let bad_env = Sidecar {- env: [("1X".to_string(), "v".to_string())].into(),- ..db- };- assert!(validate_sidecars(&[bad_env], &[]).is_err());- }-#[test]fn sidecar_json_matches_the_7887_shape() {let s = Sidecar {diff --git a/libs/cua/crates/cua-fleet/src/runtime.rs b/libs/cua/crates/cua-fleet/src/runtime.rsindex fc88ee16dc..b46d7d097b 100644--- a/libs/cua/crates/cua-fleet/src/runtime.rs+++ b/libs/cua/crates/cua-fleet/src/runtime.rs@@ -484,9 +484,7 @@ pub async fn resolve_fleet_image_with(/// The canonical image for `os` (`linux`, `windows`, `macos`), honouring/// `CUA_IMAGE_<OS>` ([`cua_image::canonical`]). Unknown OS names get Linux.pub fn canonical_image(os: &str) -> String {- cua_image::canonical::canonical_image(os, None).unwrap_or_else(|_| {- cua_image::canonical::canonical_for(cua_image::canonical::CanonicalOs::Linux, None)- })+ cua_image::canonical::canonical_image_or_linux(os)}/// A canonical alias (`linux`, `ubuntu`, `windows`, `macos[:version]`) todiff --git a/libs/cua/crates/cua-fleet/tests/reexports.rs b/libs/cua/crates/cua-fleet/tests/reexports.rsnew file mode 100644index 0000000000..a0901fbddc--- /dev/null+++ b/libs/cua/crates/cua-fleet/tests/reexports.rs@@ -0,0 +1,113 @@+//! The helpers that moved to `cua-image` are still reachable at their old+//! `cua_fleet` paths, as the same items, so callers keep compiling while they+//! switch to `cua-image`.++use std::collections::BTreeMap;++#[test]+fn build_helpers_are_cua_images() {+ // Same types: each side is assignable to the other without a conversion.+ let spec: cua_image::build::BuildSpec = cua_fleet::BuildSpec {+ from: "python:3.12-slim".into(),+ ..Default::default()+ };+ let _: cua_fleet::builds::BuildSpec = spec.clone();+ let file: cua_image::build::BuildFile = cua_fleet::BuildFile {+ source: "app.py".into(),+ destination: "/srv/app.py".into(),+ };+ let _: cua_fleet::builds::BuildFile = file;+ let _: cua_image::spec::ImageLayer = cua_fleet::ImageLayer::Run {+ command: "true".into(),+ };+ let _: cua_image::RegistryCredentials = cua_fleet::RegistryCredentials::new("me", "pw");++ // Same constants and functions.+ assert_eq!(+ cua_fleet::builds::DEFAULT_BUILD_TIMEOUT,+ cua_image::build::DEFAULT_BUILD_TIMEOUT+ );+ assert_eq!(+ cua_fleet::builds::BUILD_NAME_PREFIX,+ cua_image::build::BUILD_NAME_PREFIX+ );+ assert_eq!(+ cua_fleet::builds::MAX_BUILD_ENV,+ cua_image::build::MAX_BUILD_ENV+ );+ let recipe = cua_fleet::builds::build_recipe(&spec, "r/p@sha256:ab", vec![], None);+ assert_eq!(+ cua_fleet::builds::build_name(&recipe),+ cua_image::build::build_name(&cua_image::build::build_recipe(+ &spec,+ "r/p@sha256:ab",+ vec![],+ None+ ))+ );+ assert!(+ cua_fleet::builds::local_build_file(&cua_fleet::BuildFile {+ source: "/definitely/not/here".into(),+ destination: "/x".into(),+ })+ .is_err()+ );+}++#[test]+fn sidecar_helpers_are_cua_images() {+ let s: cua_image::sidecar::Sidecar = cua_fleet::Sidecar::new("redis:7-alpine");+ assert_eq!(s.name, cua_fleet::default_sidecar_name("redis:7-alpine"));+ assert_eq!(cua_fleet::MAX_SIDECARS, cua_image::sidecar::MAX_SIDECARS);+ assert_eq!(+ cua_fleet::MAIN_CONTAINER_NAME,+ cua_image::sidecar::MAIN_CONTAINER_NAME+ );+ assert_eq!(+ cua_fleet::RESERVED_SERVICE_NAMES,+ cua_image::sidecar::RESERVED_SERVICE_NAMES+ );+ cua_fleet::validate_sidecars(std::slice::from_ref(&s), &[]).unwrap();+ // A refusal is cua-image's error; Fleet callers get it as their own.+ let dup = [s.clone(), s];+ let e: cua_fleet::Error = cua_fleet::validate_sidecars(&dup, &[]).unwrap_err().into();+ assert!(matches!(e, cua_fleet::Error::InvalidArgument(m) if m.contains("used twice")));+ let services = BTreeMap::from([("sc".to_string(), 80u16)]);+ assert!(cua_fleet::check_reserved_service_names(services.keys(), true).is_err());+}++#[test]+fn canonical_images_follow_cua_image() {+ assert_eq!(+ cua_fleet::canonical_image("linux"),+ cua_image::canonical::canonical_image_or_linux("linux")+ );+ assert_eq!(+ cua_fleet::canonical_image("no-such-os"),+ cua_fleet::canonical_image("linux"),+ "an unknown OS gets Linux"+ );+ assert!(cua_fleet::is_canonical_image("ghcr.io/trycua/linux:24.04"));+ assert!(!cua_fleet::is_canonical_image("python:3.12-slim"));+ assert_eq!(+ cua_fleet::registry_of("ghcr.io/trycua/linux:24.04"),+ cua_image::registry_of("ghcr.io/trycua/linux:24.04")+ );+}++#[test]+fn sidecar_names_use_the_fleet_dns_label_rule() {+ // cua-image cannot depend on the Fleet SDK, so it has its own DNS-label+ // check; it must agree with the one Fleet admits.+ let long = "a".repeat(64);+ let max = "a".repeat(63);+ for name in [+ "redis", "a", "a-b", "-a", "a-", "A", "a_b", "", "9lives", "a.b", &max, &long,+ ] {+ assert_eq!(+ cua_image::spec::is_dns_label(name),+ cua_fleet::sdk::validate_dns_label(name).is_ok(),+ "{name:?}"+ );+ }+}diff --git a/libs/cua/crates/cua-image/src/build.rs b/libs/cua/crates/cua-image/src/build.rsnew file mode 100644index 0000000000..f874d61ad8--- /dev/null+++ b/libs/cua/crates/cua-image/src/build.rs@@ -0,0 +1,326 @@+//! What an image build is: [`BuildSpec`] (layers, environment, ports and+//! files on a registry base) and the content-addressed names and recipes a+//! build gets, so an identical spec is one content hash everywhere.+//!+//! A local build (`cua-daemon` into the container engine) names its image+//! with [`build_name`] of the [`build_recipe`] of the spec with the base+//! pinned by digest and each copied file referenced by its hash+//! ([`local_build_file`]). The same spec therefore finds its earlier build+//! instead of building again, and a moved base tag builds anew.++use crate::error::InvalidArgument;+use crate::spec::{+ ImageFile, ImageFileReference, ImageLayer, ImageRecipe, RecipeKind, is_env_name,+};+use serde_json::json;+use sha2::{Digest, Sha256};+use std::{collections::BTreeMap, path::PathBuf, time::Duration};++/// Prefix of content-named builds (`cua-b-<24 hex>`).+pub const BUILD_NAME_PREFIX: &str = "cua-b-";+/// Default build budget.+pub const DEFAULT_BUILD_TIMEOUT: Duration = Duration::from_secs(3600);+/// Most environment variables a build takes (the rootfs builder's limit).+pub const MAX_BUILD_ENV: usize = 128;+/// Longest environment value a build takes.+pub const MAX_BUILD_ENV_VALUE: usize = 8192;++/// What to build.+#[derive(Clone, Debug, Default, PartialEq, Eq)]+pub struct BuildSpec {+ /// Registry base image.+ pub from: String,+ /// Build steps, in order.+ pub layers: Vec<ImageLayer>,+ /// Image environment.+ pub env: BTreeMap<String, String>,+ /// Ports the image exposes.+ pub ports: Vec<u16>,+ /// Local files copied into the image.+ pub files: Vec<BuildFile>,+ /// Build budget (default one hour).+ pub timeout: Option<Duration>,+}++/// A local file copied into the image.+#[derive(Clone, Debug, PartialEq, Eq)]+pub struct BuildFile {+ /// Local path.+ pub source: PathBuf,+ /// Absolute path in the image.+ pub destination: String,+}++impl BuildSpec {+ /// Whether there is anything to build on top of `from`.+ pub fn is_empty(&self) -> bool {+ self.layers.is_empty() && self.env.is_empty() && self.files.is_empty()+ }++ /// Checks the spec (a base, no VM-only layers, env names, absolute+ /// copy destinations).+ pub fn validate(&self) -> Result<(), InvalidArgument> {+ if self.from.trim().is_empty() || self.from.chars().any(char::is_whitespace) {+ return Err(InvalidArgument(+ "an image build needs a base image reference".into(),+ ));+ }+ if self+ .layers+ .iter()+ .any(|l| matches!(l, ImageLayer::AppInstall { .. }))+ {+ return Err(InvalidArgument(+ "app_install layers need a VM image; a build on a registry base makes a \+ container image"+ .into(),+ ));+ }+ if let Some(k) = self.env.keys().find(|k| !is_env_name(k)) {+ return Err(InvalidArgument(format!(+ "bad environment variable name {k:?}"+ )));+ }+ // The rootfs builder writes each value as one Dockerfile ENV line+ // and refuses anything else; say so before building anything.+ if self.env.len() > MAX_BUILD_ENV {+ return Err(InvalidArgument(format!(+ "an image build takes at most {MAX_BUILD_ENV} environment variables (got {})",+ self.env.len()+ )));+ }+ for (k, v) in &self.env {+ if v.contains('\n') || v.contains('\r') {+ return Err(InvalidArgument(format!(+ "environment variable {k} has a multi-line value; an image build stores \+ each value as one line (encode it, or set it at runtime with env=)"+ )));+ }+ if v.len() > MAX_BUILD_ENV_VALUE {+ return Err(InvalidArgument(format!(+ "environment variable {k} is longer than {MAX_BUILD_ENV_VALUE} bytes"+ )));+ }+ }+ for f in &self.files {+ if !f.destination.starts_with('/') {+ return Err(InvalidArgument(format!(+ "copy destination {:?} must be an absolute path",+ f.destination+ )));+ }+ }+ Ok(())+ }+}++/// The content-addressed build name for a recipe (`cua-b-<24 hex>`).+pub fn build_name(recipe: &ImageRecipe) -> String {+ let canonical = serde_json::to_string(&json!({+ "domain": "cua.remote-build/v1",+ "recipe": recipe,+ }))+ .unwrap_or_default();+ format!(+ "{BUILD_NAME_PREFIX}{}",+ &hex::encode(Sha256::digest(canonical.as_bytes()))[..24]+ )+}++/// The recipe a build of `spec` on `base` (pinned by digest) makes. Builds+/// that upload their `files` and builds that reference them with+/// [`local_build_file`] are named by the same [`build_name`] of it, so an+/// identical spec is one content hash.+pub fn build_recipe(+ spec: &BuildSpec,+ base: &str,+ files: Vec<ImageFile>,+ from_pull_secret: Option<String>,+) -> ImageRecipe {+ ImageRecipe {+ distro: "registry".into(),+ version: version_of(&spec.from),+ kind: RecipeKind::Container,+ from: Some(base.to_string()),+ from_pull_secret,+ layers: spec.layers.clone(),+ env: spec.env.clone(),+ files,+ ports: {+ let mut p = spec.ports.clone();+ p.sort_unstable();+ p.dedup();+ p+ },+ ..Default::default()+ }+}++/// A local build's content-addressed reference for a `copy` file (its+/// sha256 and size), for [`build_recipe`].+pub fn local_build_file(f: &BuildFile) -> Result<ImageFile, InvalidArgument> {+ let meta = std::fs::metadata(&f.source)+ .map_err(|e| InvalidArgument(format!("copy {}: {e}", f.source.display())))?;+ if !meta.is_file() {+ return Err(InvalidArgument(format!(+ "copy {}: builds copy single files",+ f.source.display()+ )));+ }+ let bytes = std::fs::read(&f.source)+ .map_err(|e| InvalidArgument(format!("copy {}: {e}", f.source.display())))?;+ let digest = hex::encode(Sha256::digest(&bytes));+ Ok(ImageFile {+ source: ImageFileReference {+ reference: format!("uploads/local/{}", &digest[..32]),+ digest: format!("sha256:{digest}"),+ size_bytes: meta.len(),+ },+ destination: f.destination.clone(),+ })+}++/// The tag of `reference` as a recipe `version` (1..64 chars), or `latest`.+fn version_of(reference: &str) -> String {+ let no_digest = reference.split('@').next().unwrap_or(reference);+ let tag = match no_digest.rsplit_once(':') {+ Some((_, t)) if !t.contains('/') => t,+ _ => "latest",+ };+ let mut v: String = tag.chars().take(64).collect();+ if v.is_empty() {+ v = "latest".into();+ }+ v+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn local_builds_share_the_content_hash() {+ let dir = tempfile::tempdir().unwrap();+ let path = dir.path().join("app.py");+ std::fs::write(&path, b"print(1)\n").unwrap();+ let spec = BuildSpec {+ from: "python:3.12-slim".into(),+ layers: vec![ImageLayer::PipInstall {+ packages: vec!["mcp".into()],+ }],+ files: vec![BuildFile {+ source: path.clone(),+ destination: "/srv/app.py".into(),+ }],+ ports: vec![8000, 8000],+ ..Default::default()+ };+ let base = "docker.io/library/python@sha256:ab";+ let name = |spec: &BuildSpec| {+ let files = spec+ .files+ .iter()+ .map(|f| local_build_file(f).unwrap())+ .collect();+ build_name(&build_recipe(spec, base, files, None))+ };+ let first = name(&spec);+ assert!(first.starts_with(BUILD_NAME_PREFIX) && first.len() == 6 + 24);+ assert_eq!(name(&spec.clone()), first, "same spec, same name");+ // File content is part of the hash; its path is not.+ std::fs::write(&path, b"print(2)\n").unwrap();+ assert_ne!(name(&spec), first);+ let f = local_build_file(&spec.files[0]).unwrap();+ assert!(f.source.digest.starts_with("sha256:"));+ assert_eq!(f.source.size_bytes, 9);+ assert!(+ local_build_file(&BuildFile {+ source: dir.path().into(),+ destination: "/x".into()+ })+ .is_err()+ );+ }++ #[test]+ fn names_are_content_addressed() {+ let r = |cmd: &str| ImageRecipe {+ distro: "registry".into(),+ version: "3.12-slim".into(),+ kind: RecipeKind::Container,+ from: Some("docker.io/library/python@sha256:ab".into()),+ layers: vec![ImageLayer::Run {+ command: cmd.into(),+ }],+ ..Default::default()+ };+ assert_eq!(build_name(&r("true")), build_name(&r("true")));+ assert_ne!(build_name(&r("true")), build_name(&r("false")));+ let n = build_name(&r("true"));+ assert!(n.starts_with("cua-b-") && n.len() == 6 + 24);+ assert!(crate::spec::is_dns_label(&n));+ }++ #[test]+ fn versions_come_from_the_tag() {+ assert_eq!(version_of("python:3.12-slim"), "3.12-slim");+ assert_eq!(version_of("localhost:5000/app"), "latest");+ assert_eq!(version_of("r.io/a@sha256:ab"), "latest");+ assert_eq!(version_of("python:"), "latest");+ }++ #[test]+ fn specs_validate() {+ let ok = BuildSpec {+ from: "python:3.12-slim".into(),+ layers: vec![ImageLayer::PipInstall {+ packages: vec!["mcp".into()],+ }],+ ..Default::default()+ };+ ok.validate().unwrap();+ assert!(!ok.is_empty());+ let app = BuildSpec {+ layers: vec![ImageLayer::AppInstall { app_id: "x".into() }],+ ..ok.clone()+ };+ assert!(app.validate().is_err());+ let rel = BuildSpec {+ files: vec![BuildFile {+ source: "a".into(),+ destination: "rel".into(),+ }],+ ..ok.clone()+ };+ assert!(rel.validate().is_err());+ let multi = BuildSpec {+ env: [("CERT".to_string(), "line1\nline2".to_string())].into(),+ ..ok.clone()+ };+ let e = multi.validate().unwrap_err().to_string();+ assert!(e.contains("multi-line") && e.contains("CERT"), "{e}");+ let cr = BuildSpec {+ env: [("A".to_string(), "x\ry".to_string())].into(),+ ..ok.clone()+ };+ assert!(cr.validate().is_err());+ let long = BuildSpec {+ env: [("A".to_string(), "x".repeat(MAX_BUILD_ENV_VALUE + 1))].into(),+ ..ok.clone()+ };+ assert!(long.validate().is_err());+ let many = BuildSpec {+ env: (0..=MAX_BUILD_ENV)+ .map(|i| (format!("V{i}"), "1".to_string()))+ .collect(),+ ..ok.clone()+ };+ assert!(many.validate().is_err());+ let single = BuildSpec {+ env: [("A".to_string(), "one line with spaces $X".to_string())].into(),+ ..ok+ };+ single.validate().unwrap();+ assert!(BuildSpec::default().validate().is_err(), "no base image");+ }+}diff --git a/libs/cua/crates/cua-image/src/canonical.rs b/libs/cua/crates/cua-image/src/canonical.rsindex 80f6a40d0f..7e8810e027 100644--- a/libs/cua/crates/cua-image/src/canonical.rs+++ b/libs/cua/crates/cua-image/src/canonical.rs@@ -200,6 +200,12 @@ pub fn canonical_image(os: &str, version: Option<&str>) -> Result<String> {Ok(canonical_for(os, version))}+/// [`canonical_image`] with the default version for any OS name: an unknown+/// name gets Linux, the safe default for a Space or sandbox image.+pub fn canonical_image_or_linux(os: &str) -> String {+ canonical_image(os, None).unwrap_or_else(|_| canonical_for(CanonicalOs::Linux, None))+}+/// [`canonical_image`] for a parsed OS.pub fn canonical_for(os: CanonicalOs, version: Option<&str>) -> String {canonical_for_with(os, version, &|n| std::env::var(n).ok())@@ -481,6 +487,15 @@ mod tests {assert!(!is_canonical("ubuntu:24.04"));assert_eq!(alias("linux/amd64"), None);assert!(canonical_image("beos", None).is_err());+ // Any OS name has an image: an unknown one gets Linux.+ assert_eq!(+ canonical_image_or_linux("beos"),+ "ghcr.io/trycua/linux:24.04"+ );+ assert_eq!(+ canonical_image_or_linux("windows"),+ "ghcr.io/trycua/windows:2022"+ );assert!(is_canonical("ghcr.io/trycua/linux:24.04-disk"));assert!(is_canonical(&format!("ghcr.io/trycua/windows@sha256:{}",diff --git a/libs/cua/crates/cua-image/src/error.rs b/libs/cua/crates/cua-image/src/error.rsindex 8314d6d686..1c7aed16e6 100644--- a/libs/cua/crates/cua-image/src/error.rs+++ b/libs/cua/crates/cua-image/src/error.rs@@ -2,6 +2,19 @@pub type Result<T, E = ImageError> = std::result::Result<T, E>;+/// A value the caller passed that the build or sidecar rules refuse (a bad+/// base image, environment variable, copy destination, sidecar name or port).+/// The message names the value and what to change.+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]+#[error("{0}")]+pub struct InvalidArgument(pub String);++impl From<InvalidArgument> for ImageError {+ fn from(e: InvalidArgument) -> Self {+ ImageError::Spec(e.0)+ }+}+#[derive(Debug, thiserror::Error)]pub enum ImageError {#[error("invalid image reference '{0}': {1}")]diff --git a/libs/cua/crates/cua-image/src/lib.rs b/libs/cua/crates/cua-image/src/lib.rsindex 57c41ce796..232ec95fad 100644--- a/libs/cua/crates/cua-image/src/lib.rs+++ b/libs/cua/crates/cua-image/src/lib.rs@@ -19,8 +19,13 @@//! * [`spec`] — the `images.cua.ai/v1alpha1` Image resource (schemars).//! * [`builder`] — local builder: boot under `cua-vmm`, apply layers through a//! [`cua_vmm::GuestExec`], pack as containerDisk and/or rootfs, push.+//! * [`build`] — what a layered build on a registry base is+//! ([`build::BuildSpec`]) and the content-addressed names and recipes it gets.+//! * [`sidecar`] — extra containers next to a sandbox and the rules every+//! provider applies to them.pub mod auth;+pub mod build;pub mod builder;pub mod cache;pub mod canonical;@@ -36,13 +41,14 @@ pub mod publish;pub mod registry;pub mod resolve;pub mod rootfs;+pub mod sidecar;pub mod spec;pub mod testing;pub use cache::ImageCache;pub use containerdisk::ContainerDiskResolver;pub use cua_vmm::{GuestExec, RegistryCredentials, normalize_registry, registry_of};-pub use error::{ImageError, Result};+pub use error::{ImageError, InvalidArgument, Result};pub use layout::{PackedImage, push_multiarch};pub use registry::{ManifestSource, RegistryClient};pub use resolve::{Backend, ResolvedImage, Variant, resolve};diff --git a/libs/cua/crates/cua-image/src/sidecar.rs b/libs/cua/crates/cua-image/src/sidecar.rsnew file mode 100644index 0000000000..443f5a5037--- /dev/null+++ b/libs/cua/crates/cua-image/src/sidecar.rs@@ -0,0 +1,276 @@+//! Sidecars: extra containers that run next to a sandbox, and the rules a+//! sandbox with sidecars follows on every provider.+//!+//! Sidecars are addressed by name: the sandbox reaches a sidecar at its name+//! (on its declared ports) and a sidecar reaches the sandbox at+//! [`MAIN_CONTAINER_NAME`]. Containers of one sandbox share a network+//! namespace, so `localhost` works there too.++use crate::error::InvalidArgument;+use crate::spec::{is_dns_label, is_env_name};+use serde::{Deserialize, Serialize};+use std::collections::{BTreeMap, BTreeSet};++/// Most sidecars a sandbox may carry.+pub const MAX_SIDECARS: usize = 8;++/// The hostname sidecars reach the sandbox at, and a name no sidecar may+/// take.+pub const MAIN_CONTAINER_NAME: &str = "main";++/// Service names a sandbox with sidecars may not use (reserved on every+/// provider, so a spec stays portable).+pub const RESERVED_SERVICE_NAMES: [&str; 3] = ["main", "sidecars", "sc"];++/// Refuses [`RESERVED_SERVICE_NAMES`] in `services` when `has_sidecars` (a+/// sandbox without sidecars may use them).+pub fn check_reserved_service_names<'a>(+ services: impl IntoIterator<Item = &'a String>,+ has_sidecars: bool,+) -> Result<(), InvalidArgument> {+ if !has_sidecars {+ return Ok(());+ }+ if let Some(n) = services+ .into_iter()+ .find(|n| RESERVED_SERVICE_NAMES.contains(&n.as_str()))+ {+ return Err(InvalidArgument(format!(+ "service name {n:?} is reserved in a sandbox with sidecars (reserved: {})",+ RESERVED_SERVICE_NAMES.join(", ")+ )));+ }+ Ok(())+}++/// An extra container next to a sandbox. The sandbox reaches it at its+/// `name` as a hostname (on its declared `ports`), and it reaches the+/// sandbox at [`MAIN_CONTAINER_NAME`]. Local containers share one network+/// namespace, so `localhost` works there too.+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]+pub struct Sidecar {+ /// Name, unique within the sandbox (DNS label, not `main`); also its+ /// hostname.+ pub name: String,+ /// Image reference.+ pub image: String,+ /// argv replacing the image's ENTRYPOINT.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub command: Option<Vec<String>>,+ /// Environment (plain values, not secrets).+ #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]+ pub env: BTreeMap<String, String>,+ /// Ports it listens on.+ #[serde(default, skip_serializing_if = "Vec::is_empty")]+ pub ports: Vec<u16>,+ /// Arguments after `command` (or the image's entrypoint).+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub args: Option<Vec<String>>,+ /// CPU request as a Kubernetes quantity (`500m`, `1`). Cloud only.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub cpu: Option<String>,+ /// Memory request as a Kubernetes quantity (`256Mi`). Cloud only.+ #[serde(default, skip_serializing_if = "Option::is_none")]+ pub memory: Option<String>,+}++impl Sidecar {+ /// A sidecar running `image`, named after the image's repository.+ pub fn new(image: impl Into<String>) -> Self {+ let image = image.into();+ Self {+ name: default_sidecar_name(&image),+ image,+ command: None,+ env: BTreeMap::new(),+ ports: vec![],+ args: None,+ cpu: None,+ memory: None,+ }+ }+}++/// `redis` for `docker.io/library/redis:7-alpine`: the last path segment of+/// the repository, lowercased to a DNS label.+pub fn default_sidecar_name(image: &str) -> String {+ let repo = image.split('@').next().unwrap_or(image);+ let last = repo.rsplit('/').next().unwrap_or(repo);+ let last = last.split(':').next().unwrap_or(last);+ let mut name: String = last+ .chars()+ .map(|c| {+ if c.is_ascii_alphanumeric() {+ c.to_ascii_lowercase()+ } else {+ '-'+ }+ })+ .collect();+ name = name.trim_matches('-').to_string();+ name.truncate(50);+ let name = name.trim_end_matches('-').to_string();+ if name.is_empty() || name == MAIN_CONTAINER_NAME {+ "sidecar".into()+ } else {+ name+ }+}++/// Checks sidecars before anything is created: at most [`MAX_SIDECARS`],+/// unique DNS-label names other than `main`, an image each, valid env names,+/// ports in range and not claimed by two sidecars. `reserved` ports belong to+/// the sandbox itself (its spacesd); services may target sidecar ports.+pub fn validate_sidecars(sidecars: &[Sidecar], reserved: &[u16]) -> Result<(), InvalidArgument> {+ if sidecars.len() > MAX_SIDECARS {+ return Err(InvalidArgument(format!(+ "at most {MAX_SIDECARS} sidecars (got {})",+ sidecars.len()+ )));+ }+ let mut names = BTreeSet::new();+ let mut ports: BTreeMap<u16, String> = BTreeMap::new();+ for s in sidecars {+ if !is_dns_label(&s.name) || s.name == MAIN_CONTAINER_NAME {+ return Err(InvalidArgument(format!(+ "sidecar name {:?} must be a DNS label other than \"main\"",+ s.name+ )));+ }+ if !names.insert(s.name.as_str()) {+ return Err(InvalidArgument(format!(+ "sidecar name {:?} is used twice",+ s.name+ )));+ }+ if s.image.trim().is_empty() {+ return Err(InvalidArgument(format!(+ "sidecar {:?} needs an image",+ s.name+ )));+ }+ if let Some(k) = s.env.keys().find(|k| !is_env_name(k)) {+ return Err(InvalidArgument(format!(+ "sidecar {:?}: bad environment variable name {k:?}",+ s.name+ )));+ }+ for p in &s.ports {+ if *p == 0 {+ return Err(InvalidArgument(format!("sidecar {:?}: port 0", s.name)));+ }+ if reserved.contains(p) {+ return Err(InvalidArgument(format!(+ "sidecar {:?} port {p} is also a sandbox port (containers share one \+ network namespace)",+ s.name+ )));+ }+ if let Some(other) = ports.insert(*p, s.name.clone()) {+ return Err(InvalidArgument(format!(+ "port {p} is claimed by sidecars {other:?} and {:?}",+ s.name+ )));+ }+ }+ }+ Ok(())+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn default_names_are_dns_labels() {+ assert_eq!(default_sidecar_name("redis:7-alpine"), "redis");+ assert_eq!(+ default_sidecar_name("docker.io/library/postgres@sha256:ab"),+ "postgres"+ );+ assert_eq!(default_sidecar_name("ghcr.io/me/My_Svc:1"), "my-svc");+ assert_eq!(default_sidecar_name("reg:5000/main"), "sidecar");+ }++ #[test]+ fn sidecars_validate() {+ let db = Sidecar {+ ports: vec![6379],+ ..Sidecar::new("redis:7-alpine")+ };+ validate_sidecars(std::slice::from_ref(&db), &[8000]).unwrap();+ assert!(+ validate_sidecars(&[db.clone(), db.clone()], &[]).is_err(),+ "dup name"+ );+ assert!(+ validate_sidecars(std::slice::from_ref(&db), &[6379]).is_err(),+ "port clash"+ );+ let twin = Sidecar {+ name: "db2".into(),+ ..db.clone()+ };+ assert!(+ validate_sidecars(&[db.clone(), twin], &[]).is_err(),+ "shared port"+ );+ let main = Sidecar {+ name: "main".into(),+ ..db.clone()+ };+ assert!(validate_sidecars(&[main], &[]).is_err());+ let many: Vec<Sidecar> = (0..9)+ .map(|i| Sidecar {+ name: format!("s{i}"),+ ports: vec![],+ ..db.clone()+ })+ .collect();+ assert!(validate_sidecars(&many, &[]).is_err());+ let bad_env = Sidecar {+ env: [("1X".to_string(), "v".to_string())].into(),+ ..db.clone()+ };+ assert!(validate_sidecars(&[bad_env], &[]).is_err());+ let no_image = Sidecar {+ image: " ".into(),+ ..db.clone()+ };+ assert!(validate_sidecars(&[no_image], &[]).is_err());+ let upper = Sidecar {+ name: "Redis".into(),+ ..db.clone()+ };+ assert!(validate_sidecars(&[upper], &[]).is_err(), "not a DNS label");+ let port0 = Sidecar {+ ports: vec![0],+ ..db+ };+ assert!(validate_sidecars(&[port0], &[]).is_err());+ }++ #[test]+ fn reserved_service_names_need_sidecars() {+ let services = ["web".to_string(), "sc".to_string()];+ check_reserved_service_names(services.iter(), false).unwrap();+ let e = check_reserved_service_names(services.iter(), true).unwrap_err();+ assert!(e.0.contains("\"sc\""), "{e}");+ check_reserved_service_names(["web".to_string()].iter(), true).unwrap();+ }++ #[test]+ fn serde_skips_empty_fields() {+ let s = Sidecar {+ ports: vec![6379],+ ..Sidecar::new("redis:7-alpine")+ };+ let v = serde_json::to_value(&s).unwrap();+ assert_eq!(+ v,+ serde_json::json!({"name": "redis", "image": "redis:7-alpine", "ports": [6379]})+ );+ let back: Sidecar = serde_json::from_value(v).unwrap();+ assert_eq!(back, s);+ }+}diff --git a/libs/cua/crates/cua-sandbox-core/src/lib.rs b/libs/cua/crates/cua-sandbox-core/src/lib.rsindex 8481b2a9de..1cfc0160a4 100644--- a/libs/cua/crates/cua-sandbox-core/src/lib.rs+++ b/libs/cua/crates/cua-sandbox-core/src/lib.rs@@ -191,5 +191,12 @@ fn provider_not_configured(p: &ProviderKind) -> String {}}+impl From<cua_image::InvalidArgument> for Error {+ /// A build spec, sidecar or service name the image rules refuse.+ fn from(e: cua_image::InvalidArgument) -> Self {+ Error::InvalidArgument(e.0)+ }+}+/// Result alias.pub type Result<T, E = Error> = std::result::Result<T, E>;diff --git a/libs/cua/crates/cua-sandbox-core/src/pool_image.rs b/libs/cua/crates/cua-sandbox-core/src/pool_image.rsindex 686eae03a5..f4aa9ec6f6 100644--- a/libs/cua/crates/cua-sandbox-core/src/pool_image.rs+++ b/libs/cua/crates/cua-sandbox-core/src/pool_image.rs@@ -9,8 +9,8 @@//! digest when the reference is digest-pinned.use crate::runtime::ImageInfo;-use cua_fleet::{FleetClient, RegistryCredentials, RuntimeKind};-use cua_image::resolve::Backend;+use cua_fleet::{FleetClient, RuntimeKind};+use cua_image::{RegistryCredentials, resolve::Backend};use std::{collections::HashMap,sync::{Mutex, OnceLock},diff --git a/libs/cua/crates/cua-sandbox-core/src/runtime.rs b/libs/cua/crates/cua-sandbox-core/src/runtime.rsindex bd4caef190..ce082bb9a6 100644--- a/libs/cua/crates/cua-sandbox-core/src/runtime.rs+++ b/libs/cua/crates/cua-sandbox-core/src/runtime.rs@@ -445,8 +445,8 @@ pub trait LocalRuntime: Send + Sync {/// ([`RuntimeError::UnsupportedImage`]).async fn build_image(&self,- spec: &cua_fleet::BuildSpec,- creds: Option<&cua_fleet::RegistryCredentials>,+ spec: &cua_image::build::BuildSpec,+ creds: Option<&cua_image::RegistryCredentials>,) -> RuntimeResult<String> {let _ = (spec, creds);Err(RuntimeError::Unsupported {diff --git a/libs/cua/crates/cua-sandbox-core/src/sandbox.rs b/libs/cua/crates/cua-sandbox-core/src/sandbox.rsindex 254ac1190e..ad6cc10750 100644--- a/libs/cua/crates/cua-sandbox-core/src/sandbox.rs+++ b/libs/cua/crates/cua-sandbox-core/src/sandbox.rs@@ -12,7 +12,12 @@ use cua_fleet::{AcquireOpts, BoundSandbox, ClaimOptions, FleetClient, ManagedClaim, PoolManager, PoolSpecKey,RuntimeKind,};-pub use cua_fleet::{BuildFile, BuildSpec, ImageLayer, RegistryCredentials, Sidecar};+pub use cua_image::{+ RegistryCredentials,+ build::{BuildFile, BuildSpec},+ sidecar::Sidecar,+ spec::ImageLayer,+};use cua_spacesd_client::{ConnectOptions, SpacesdClient};use crate::placement::{self, Kind, On, Runtime};@@ -399,7 +404,7 @@ impl CreateOptions {}_ => image,};- c.for_registry(cua_fleet::registry_of(reference))+ c.for_registry(cua_image::registry_of(reference))}})}@@ -423,7 +428,7 @@ impl CreateOptions {{return None;}- cua_fleet::is_canonical_image(&self.image).then_some(true)+ cua_image::canonical::is_canonical(&self.image).then_some(true)})}@@ -625,7 +630,7 @@ impl CreateOptions {if let Some(c) = &creds&& std::iter::once(&image.image).chain(self.sidecars.iter().map(|s| &s.image))- .any(|i| c.applies_to(cua_fleet::registry_of(i)))+ .any(|i| c.applies_to(cua_image::registry_of(i))){let registry = c.registry.clone().unwrap_or_default();key.pull_secret = Some(cua_fleet::registry_secret_name(®istry, &c.username));@@ -684,8 +689,8 @@ impl CreateOptions {if self.sidecars.is_empty() {return Ok(());}- cua_fleet::validate_sidecars(&self.sidecars, &[])?;- cua_fleet::check_reserved_service_names(self.services.keys(), true)?;+ cua_image::sidecar::validate_sidecars(&self.sidecars, &[])?;+ cua_image::sidecar::check_reserved_service_names(self.services.keys(), true)?;Ok(())}diff --git a/libs/cua/crates/cua-sandbox-core/tests/parity.rs b/libs/cua/crates/cua-sandbox-core/tests/parity.rsindex 400ef4f59c..a25170d2df 100644--- a/libs/cua/crates/cua-sandbox-core/tests/parity.rs+++ b/libs/cua/crates/cua-sandbox-core/tests/parity.rs@@ -236,7 +236,7 @@ async fn reserved_names_and_bad_sidecars_fail_before_anything_starts() {.build();cua_fleet::testing::set_image_variant(ROOTFS, cua_fleet::ImageVariant::Rootfs);for provider in [ProviderKind::Local, ProviderKind::Fleet] {- for reserved in cua_fleet::RESERVED_SERVICE_NAMES {+ for reserved in cua_image::sidecar::RESERVED_SERVICE_NAMES {let mut o = CreateOptions::new(provider, ROOTFS).sidecar(redis()).service(reserved, 8080);