sail/

image.rs

//! Typed image specification for
//! [`CreateSailboxRequest`](crate::sailbox::types::CreateSailboxRequest).
//!
//! These mirror the `image.v1.ImageSpec` proto and serialize to the canonical
//! proto-JSON the backend accepts: camelCase field names, enum value names, and
//! each oneof arm as a direct field. The higher-level image-building DSL
//! (reading local files, hashing contents) lives in the language wrapper; this
//! is the typed wire spec the core sends.

use std::collections::HashMap;

use serde::{Deserialize, Serialize};

/// A Sailbox image: a base or registry image plus ordered build steps.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct ImageSpec {
    /// Base image to build on; mutually exclusive with `oci`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub base: Option<BaseImage>,
    /// Your own image used as the root filesystem; mutually exclusive with
    /// `base`. Names a Debian- or Ubuntu-based image on a supported public
    /// registry (`docker.io`, `ghcr.io`, `public.ecr.aws`, or `quay.io`) by
    /// tag, digest, or bare name (a bare name means the `latest` tag). Once
    /// Sail has a built image for a tag, later builds keep using that image
    /// after the tag moves. If no image was ever built from a lookup, Sail
    /// may look the tag up again later. A forced build
    /// ([`BuildMode::ForceBuild`](crate::imagebuild::BuildMode)) looks the
    /// tag up again and builds the version it points at now. A digest names
    /// exactly one image, so it never moves.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub oci: Option<OciImage>,
    /// Ordered build steps applied on top of the image source.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub build_steps: Vec<ImageBuildStep>,
    /// Environment variables baked into the image.
    #[serde(skip_serializing_if = "HashMap::is_empty")]
    pub env: HashMap<String, String>,
    /// Target CPU architecture. Unset means amd64 with `base`, and with `oci`
    /// means whichever architecture the registry image was built for (amd64
    /// when it was built for both). Setting it with `oci` requires the image
    /// to provide that architecture.
    #[serde(skip_serializing_if = "ImageArchitecture::is_unspecified")]
    pub architecture: ImageArchitecture,
    /// Exact Python version to install as `python3`; empty uses the builder
    /// default. Not accepted with `oci`: a registry image keeps its own
    /// `python3`.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub python_version: String,
    /// Writable root filesystem; unspecified preserves the ext4 default.
    #[serde(skip_serializing_if = "ImageFilesystem::is_unspecified")]
    pub filesystem: ImageFilesystem,
}

/// Your own image from a registry, named by reference.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct OciImage {
    /// Registry reference, e.g. `docker.io/library/ubuntu:24.04` or
    /// `docker.io/library/ubuntu@sha256:<64 hex>`.
    #[serde(rename = "ref", skip_serializing_if = "String::is_empty")]
    pub reference: String,
}

/// A supported base image. Absence of a base is `None`, not a variant here.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum BaseImage {
    /// Debian.
    #[serde(rename = "BASE_IMAGE_DEBIAN")]
    Debian,
    /// Debian plus a baked dev layer (node LTS, build tools, editor-server OS
    /// prerequisites). Prebuilt only: supports no python_version, build steps,
    /// or env.
    #[serde(rename = "BASE_IMAGE_DEVBOX")]
    Devbox,
}

/// A target CPU architecture.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum ImageArchitecture {
    /// Unset; see [`ImageSpec::architecture`] for what each source defaults to.
    #[default]
    #[serde(rename = "IMAGE_ARCHITECTURE_UNSPECIFIED")]
    Unspecified,
    /// x86-64.
    #[serde(rename = "IMAGE_ARCHITECTURE_AMD64")]
    Amd64,
    /// ARM64.
    #[serde(rename = "IMAGE_ARCHITECTURE_ARM64")]
    Arm64,
}

impl ImageArchitecture {
    // Takes `&self` because serde's `skip_serializing_if` requires a `fn(&T)`.
    #[allow(clippy::trivially_copy_pass_by_ref)]
    fn is_unspecified(&self) -> bool {
        matches!(self, ImageArchitecture::Unspecified)
    }
}

/// Writable root filesystem for the image artifact.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum ImageFilesystem {
    /// Unset; equivalent to ext4 for backward compatibility.
    #[default]
    #[serde(rename = "IMAGE_FILESYSTEM_UNSPECIFIED")]
    Unspecified,
    /// ext4 writable root filesystem.
    #[serde(rename = "IMAGE_FILESYSTEM_EXT4")]
    Ext4,
    /// Btrfs writable root filesystem.
    #[serde(rename = "IMAGE_FILESYSTEM_BTRFS")]
    Btrfs,
}

impl ImageFilesystem {
    #[allow(clippy::trivially_copy_pass_by_ref)]
    fn is_unspecified(&self) -> bool {
        matches!(self, ImageFilesystem::Unspecified)
    }
}

/// One build step: exactly one operation (the proto's `step` oneof).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum ImageBuildStep {
    /// Install system packages with apt.
    AptInstall(PackageInstall),
    /// Install Python packages with pip.
    PipInstall(PackageInstall),
    /// Run a shell command.
    RunCommand(RunCommand),
    /// Add one local file, referenced by its content hash.
    AddLocalFile(AddLocalFile),
    /// Add a tree of local files.
    AddLocalDir(AddLocalDir),
}

/// A set of packages to install.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct PackageInstall {
    /// Package names.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub packages: Vec<String>,
}

/// A shell command to run during the build.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct RunCommand {
    /// The command line.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub command: String,
}

/// One local file copied into the image at `remote_path`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct AddLocalFile {
    /// Lowercase hex sha256 of the file contents.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub content_sha256: String,
    /// Absolute path inside the rootfs.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub remote_path: String,
    /// Permission bits (low 9); `0` means the builder default (0644).
    #[serde(skip_serializing_if = "is_zero")]
    pub mode: u32,
}

/// A tree of local files copied into the image under `remote_path`.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct AddLocalDir {
    /// Absolute path inside the rootfs where the files land.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub remote_path: String,
    /// The files in the tree.
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub files: Vec<AddLocalDirFile>,
}

/// One file within an [`AddLocalDir`].
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", default)]
pub struct AddLocalDirFile {
    /// Path relative to the dir's `remote_path`.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub relative_path: String,
    /// Lowercase hex sha256 of the file contents.
    #[serde(skip_serializing_if = "String::is_empty")]
    pub content_sha256: String,
    /// Permission bits (low 9); `0` means the builder default (0644).
    #[serde(skip_serializing_if = "is_zero")]
    pub mode: u32,
}

// Takes `&u32` because serde's `skip_serializing_if` requires a `fn(&T)`.
#[allow(clippy::trivially_copy_pass_by_ref)]
fn is_zero(n: &u32) -> bool {
    *n == 0
}