zlayer_types/spec/

types.rs

//! `ZLayer` V1 Service Specification Types
//!
//! This module defines all types for parsing and validating `ZLayer` deployment specs.

mod duration {
    use humantime::format_duration;
    use serde::{Deserialize, Deserializer, Serializer};
    use std::time::Duration;

    #[allow(clippy::ref_option)]
    pub fn serialize<S>(duration: &Option<Duration>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        match duration {
            Some(d) => serializer.serialize_str(&format_duration(*d).to_string()),
            None => serializer.serialize_none(),
        }
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<Duration>, D::Error>
    where
        D: Deserializer<'de>,
    {
        use serde::de::Error;
        let s: Option<String> = Option::deserialize(deserializer)?;
        match s {
            Some(s) => humantime::parse_duration(&s)
                .map(Some)
                .map_err(|e| D::Error::custom(format!("invalid duration: {e}"))),
            None => Ok(None),
        }
    }

    pub mod option {
        pub use super::*;
    }

    /// Serde module for required (non-Option) Duration fields
    pub mod required {
        use humantime::format_duration;
        use serde::{Deserialize, Deserializer, Serializer};
        use std::time::Duration;

        pub fn serialize<S>(duration: &Duration, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            serializer.serialize_str(&format_duration(*duration).to_string())
        }

        pub fn deserialize<'de, D>(deserializer: D) -> Result<Duration, D::Error>
        where
            D: Deserializer<'de>,
        {
            use serde::de::Error;
            let s: String = String::deserialize(deserializer)?;
            humantime::parse_duration(&s)
                .map_err(|e| D::Error::custom(format!("invalid duration: {e}")))
        }
    }
}

use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use validator::Validate;

/// How service replicas are allocated to nodes
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum NodeMode {
    /// Containers placed on any node with capacity (default, bin-packing)
    #[default]
    Shared,
    /// Each replica gets its own dedicated node (1:1 mapping)
    Dedicated,
    /// Service is the ONLY thing on its nodes (no other services)
    Exclusive,
}

/// Service type - determines runtime behavior and scaling model
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ServiceType {
    /// Standard long-running container service
    #[default]
    Standard,
    /// WASM-based HTTP service (wasi:http/incoming-handler)
    WasmHttp,
    /// WASM-based general plugin (zlayer:plugin handler - full host access)
    WasmPlugin,
    /// WASM-based stateless request/response transformer
    WasmTransformer,
    /// WASM-based authenticator plugin (secrets + KV + HTTP)
    WasmAuthenticator,
    /// WASM-based rate limiter (KV + metrics)
    WasmRateLimiter,
    /// WASM-based request/response middleware
    WasmMiddleware,
    /// WASM-based custom router
    WasmRouter,
    /// Run-to-completion job
    Job,
}

/// Storage performance tier
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum StorageTier {
    /// Direct local filesystem (SSD/NVMe) - SQLite-safe, fast fsync
    #[default]
    Local,
    /// bcache-backed tiered storage (SSD cache + slower backend)
    Cached,
    /// NFS/network storage - NOT SQLite-safe (will warn)
    Network,
}

/// Node selection constraints for service placement
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NodeSelector {
    /// Required labels that nodes must have (all must match)
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub labels: HashMap<String, String>,
    /// Preferred labels (soft constraint, nodes with these are preferred)
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub prefer_labels: HashMap<String, String>,
}

/// Operating system a service needs to run on.
///
/// Mirrors the OS half of an OCI platform descriptor. Canonical wire strings
/// match Go's `GOOS` values (e.g. `"linux"`, `"windows"`, `"darwin"`).
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, utoipa::ToSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum OsKind {
    Linux,
    Windows,
    Macos,
}

impl OsKind {
    /// Canonical OCI-style string (`"linux"` / `"windows"` / `"darwin"`).
    /// This is the same convention `Runtime.platform_resolver` uses.
    #[must_use]
    pub const fn as_oci_str(self) -> &'static str {
        match self {
            OsKind::Linux => "linux",
            OsKind::Windows => "windows",
            OsKind::Macos => "darwin",
        }
    }

    /// Detect from `std::env::consts::OS`. Unknown values return `None`.
    #[must_use]
    pub fn from_rust_os(s: &str) -> Option<Self> {
        match s {
            "linux" => Some(Self::Linux),
            "windows" => Some(Self::Windows),
            "macos" => Some(Self::Macos),
            _ => None,
        }
    }

    /// Parse the OCI-canonical OS string as written in an image manifest's
    /// `config.os` field (lowercase: `"linux"` / `"windows"` / `"darwin"`).
    /// Unknown or empty values return `None`.
    ///
    /// This is the inverse of [`Self::as_oci_str`] and is used by the
    /// registry's manifest-OS inspection (see `fetch_image_os`).
    #[must_use]
    pub fn from_oci_str(s: &str) -> Option<Self> {
        match s {
            "linux" => Some(Self::Linux),
            "windows" => Some(Self::Windows),
            "darwin" => Some(Self::Macos),
            _ => None,
        }
    }
}

/// CPU architecture a service needs. Mirrors the arch half of an OCI platform.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, utoipa::ToSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum ArchKind {
    Amd64,
    Arm64,
}

impl ArchKind {
    /// Canonical OCI-style string (`"amd64"` / `"arm64"`).
    #[must_use]
    pub const fn as_oci_str(self) -> &'static str {
        match self {
            ArchKind::Amd64 => "amd64",
            ArchKind::Arm64 => "arm64",
        }
    }

    /// Detect from `std::env::consts::ARCH`. Unknown values return `None`.
    #[must_use]
    pub fn from_rust_arch(s: &str) -> Option<Self> {
        match s {
            "x86_64" => Some(Self::Amd64),
            "aarch64" => Some(Self::Arm64),
            _ => None,
        }
    }
}

/// Platform a service targets. `None` on `ServiceSpec.platform` means
/// "any agent is acceptable" (preserves backward compatibility).
//
// NOTE: no `Copy`. `os_version: Option<String>` rules it out. `OsKind` / `ArchKind`
// are still `Copy`, so field-level borrows stay ergonomic.
#[derive(
    Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize, utoipa::ToSchema,
)]
pub struct TargetPlatform {
    pub os: OsKind,
    pub arch: ArchKind,
    /// Optional OS version constraint — primarily for Windows multi-platform
    /// images, where `platform.os.version` in the OCI index distinguishes build
    /// families (e.g. `10.0.26100.*` for Server 2025 / Win11 24H2,
    /// `10.0.20348.*` for Server 2022). When set on a Windows target the
    /// registry platform resolver prefers manifest entries whose `os.version`
    /// matches this value exactly or shares a `major.minor.build` prefix.
    /// Unused on Linux/macOS platforms.
    #[serde(default, rename = "osVersion", skip_serializing_if = "Option::is_none")]
    pub os_version: Option<String>,
}

impl TargetPlatform {
    #[must_use]
    pub const fn new(os: OsKind, arch: ArchKind) -> Self {
        Self {
            os,
            arch,
            os_version: None,
        }
    }

    /// Constrain the platform to a specific `os.version` string.
    ///
    /// Applies to Windows targets: the registry resolver matches manifest
    /// entries whose `platform.os.version` equals this value or starts with it
    /// (treated as a `major.minor.build` prefix). Has no effect on Linux/macOS.
    #[must_use]
    pub fn with_os_version(mut self, v: impl Into<String>) -> Self {
        self.os_version = Some(v.into());
        self
    }

    /// Canonical OCI-style string (`"linux/amd64"`, `"windows/arm64"`).
    ///
    /// Does NOT include `os_version` — use [`Self::as_detailed_str`] when the
    /// version matters (e.g. for error/log messages that need to distinguish
    /// between Windows build families).
    #[must_use]
    pub fn as_oci_str(self) -> String {
        format!("{}/{}", self.os.as_oci_str(), self.arch.as_oci_str())
    }

    /// Like [`Self::as_oci_str`] but appends ` (os.version=…)` when an
    /// `os_version` constraint is set. Intended for diagnostics, not for
    /// matching against manifest entries.
    #[must_use]
    pub fn as_detailed_str(&self) -> String {
        match &self.os_version {
            Some(v) => format!(
                "{}/{} (os.version={v})",
                self.os.as_oci_str(),
                self.arch.as_oci_str()
            ),
            None => format!("{}/{}", self.os.as_oci_str(), self.arch.as_oci_str()),
        }
    }
}

impl std::fmt::Display for TargetPlatform {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}/{}", self.os.as_oci_str(), self.arch.as_oci_str())
    }
}

/// Explicit capability declarations for WASM modules.
/// Controls which host interfaces are linked and available to the component.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[allow(clippy::struct_excessive_bools)]
pub struct WasmCapabilities {
    /// Config interface access (zlayer:plugin/config)
    #[serde(default = "default_true")]
    pub config: bool,
    /// Key-value storage access (zlayer:plugin/keyvalue)
    #[serde(default = "default_true")]
    pub keyvalue: bool,
    /// Logging access (zlayer:plugin/logging)
    #[serde(default = "default_true")]
    pub logging: bool,
    /// Secrets access (zlayer:plugin/secrets)
    #[serde(default)]
    pub secrets: bool,
    /// Metrics emission (zlayer:plugin/metrics)
    #[serde(default = "default_true")]
    pub metrics: bool,
    /// HTTP client for outgoing requests (wasi:http/outgoing-handler)
    #[serde(default)]
    pub http_client: bool,
    /// WASI CLI access (args, env, stdio)
    #[serde(default)]
    pub cli: bool,
    /// WASI filesystem access
    #[serde(default)]
    pub filesystem: bool,
    /// WASI sockets access (TCP/UDP)
    #[serde(default)]
    pub sockets: bool,
}

impl Default for WasmCapabilities {
    fn default() -> Self {
        Self {
            config: true,
            keyvalue: true,
            logging: true,
            secrets: false,
            metrics: true,
            http_client: false,
            cli: false,
            filesystem: false,
            sockets: false,
        }
    }
}

/// Pre-opened directory for WASM filesystem access
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct WasmPreopen {
    /// Host path to mount
    pub source: String,
    /// Guest path (visible to WASM module)
    pub target: String,
    /// Read-only access (default: false)
    #[serde(default)]
    pub readonly: bool,
}

/// Comprehensive configuration for all WASM service types.
///
/// Replaces the previous `WasmHttpConfig` with resource limits, capability
/// declarations, networking controls, and storage configuration.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
#[allow(clippy::struct_excessive_bools)]
pub struct WasmConfig {
    // --- Instance Management ---
    /// Minimum number of warm instances to keep ready
    #[serde(default = "default_min_instances")]
    pub min_instances: u32,
    /// Maximum number of instances to scale to
    #[serde(default = "default_max_instances")]
    pub max_instances: u32,
    /// Time before idle instances are terminated
    #[serde(default = "default_idle_timeout", with = "duration::required")]
    pub idle_timeout: std::time::Duration,
    /// Maximum time for a single request
    #[serde(default = "default_request_timeout", with = "duration::required")]
    pub request_timeout: std::time::Duration,

    // --- Resource Limits ---
    /// Maximum linear memory (e.g., "64Mi", "256Mi")
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_memory: Option<String>,
    /// Maximum fuel (instruction count limit, 0 = unlimited)
    #[serde(default)]
    pub max_fuel: u64,
    /// Epoch interval for cooperative preemption
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        with = "duration::option"
    )]
    pub epoch_interval: Option<std::time::Duration>,

    // --- Capabilities ---
    /// Explicit capability grants (overrides world defaults when restricting)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub capabilities: Option<WasmCapabilities>,

    // --- Networking ---
    /// Allow outgoing HTTP requests (default: true)
    #[serde(default = "default_true")]
    pub allow_http_outgoing: bool,
    /// Allowed outgoing HTTP hosts (empty = all allowed)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_hosts: Vec<String>,
    /// Allow raw TCP sockets (default: false)
    #[serde(default)]
    pub allow_tcp: bool,
    /// Allow raw UDP sockets (default: false)
    #[serde(default)]
    pub allow_udp: bool,

    // --- Storage ---
    /// Pre-opened directories (host path -> guest path)
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub preopens: Vec<WasmPreopen>,
    /// Enable KV store access (default: true)
    #[serde(default = "default_true")]
    pub kv_enabled: bool,
    /// KV store namespace (default: service name)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kv_namespace: Option<String>,
    /// KV store max value size in bytes (default: 1MB)
    #[serde(default = "default_kv_max_value_size")]
    pub kv_max_value_size: u64,

    // --- Secrets ---
    /// Secret names accessible to this WASM module
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub secrets: Vec<String>,

    // --- Performance ---
    /// Pre-compile on deploy to reduce cold start (default: true)
    #[serde(default = "default_true")]
    pub precompile: bool,
}

fn default_kv_max_value_size() -> u64 {
    1_048_576 // 1MB
}

impl Default for WasmConfig {
    fn default() -> Self {
        Self {
            min_instances: default_min_instances(),
            max_instances: default_max_instances(),
            idle_timeout: default_idle_timeout(),
            request_timeout: default_request_timeout(),
            max_memory: None,
            max_fuel: 0,
            epoch_interval: None,
            capabilities: None,
            allow_http_outgoing: true,
            allowed_hosts: Vec::new(),
            allow_tcp: false,
            allow_udp: false,
            preopens: Vec::new(),
            kv_enabled: true,
            kv_namespace: None,
            kv_max_value_size: default_kv_max_value_size(),
            secrets: Vec::new(),
            precompile: true,
        }
    }
}

/// Configuration for WASM HTTP services with instance pooling
#[deprecated(note = "Use WasmConfig instead")]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct WasmHttpConfig {
    /// Minimum number of warm instances to keep ready
    #[serde(default = "default_min_instances")]
    pub min_instances: u32,
    /// Maximum number of instances to scale to
    #[serde(default = "default_max_instances")]
    pub max_instances: u32,
    /// Time before idle instances are terminated
    #[serde(default = "default_idle_timeout", with = "duration::required")]
    pub idle_timeout: std::time::Duration,
    /// Maximum time for a single request
    #[serde(default = "default_request_timeout", with = "duration::required")]
    pub request_timeout: std::time::Duration,
}

fn default_min_instances() -> u32 {
    0
}

fn default_max_instances() -> u32 {
    10
}

fn default_idle_timeout() -> std::time::Duration {
    std::time::Duration::from_secs(300)
}

fn default_request_timeout() -> std::time::Duration {
    std::time::Duration::from_secs(30)
}

#[allow(deprecated)]
impl Default for WasmHttpConfig {
    fn default() -> Self {
        Self {
            min_instances: default_min_instances(),
            max_instances: default_max_instances(),
            idle_timeout: default_idle_timeout(),
            request_timeout: default_request_timeout(),
        }
    }
}

#[allow(deprecated)]
impl From<WasmHttpConfig> for WasmConfig {
    fn from(old: WasmHttpConfig) -> Self {
        Self {
            min_instances: old.min_instances,
            max_instances: old.max_instances,
            idle_timeout: old.idle_timeout,
            request_timeout: old.request_timeout,
            ..Default::default()
        }
    }
}

impl ServiceType {
    /// Returns true if this is any WASM service type
    #[must_use]
    pub fn is_wasm(&self) -> bool {
        matches!(
            self,
            ServiceType::WasmHttp
                | ServiceType::WasmPlugin
                | ServiceType::WasmTransformer
                | ServiceType::WasmAuthenticator
                | ServiceType::WasmRateLimiter
                | ServiceType::WasmMiddleware
                | ServiceType::WasmRouter
        )
    }

    /// Returns the default capabilities for this WASM service type.
    /// Returns None for non-WASM types.
    #[must_use]
    pub fn default_wasm_capabilities(&self) -> Option<WasmCapabilities> {
        match self {
            ServiceType::WasmHttp | ServiceType::WasmRouter => Some(WasmCapabilities {
                config: true,
                keyvalue: true,
                logging: true,
                secrets: false,
                metrics: false,
                http_client: true,
                cli: false,
                filesystem: false,
                sockets: false,
            }),
            ServiceType::WasmPlugin => Some(WasmCapabilities {
                config: true,
                keyvalue: true,
                logging: true,
                secrets: true,
                metrics: true,
                http_client: true,
                cli: true,
                filesystem: true,
                sockets: false,
            }),
            ServiceType::WasmTransformer => Some(WasmCapabilities {
                config: false,
                keyvalue: false,
                logging: true,
                secrets: false,
                metrics: false,
                http_client: false,
                cli: true,
                filesystem: false,
                sockets: false,
            }),
            ServiceType::WasmAuthenticator => Some(WasmCapabilities {
                config: true,
                keyvalue: false,
                logging: true,
                secrets: true,
                metrics: false,
                http_client: true,
                cli: false,
                filesystem: false,
                sockets: false,
            }),
            ServiceType::WasmRateLimiter => Some(WasmCapabilities {
                config: true,
                keyvalue: true,
                logging: true,
                secrets: false,
                metrics: true,
                http_client: false,
                cli: true,
                filesystem: false,
                sockets: false,
            }),
            ServiceType::WasmMiddleware => Some(WasmCapabilities {
                config: true,
                keyvalue: false,
                logging: true,
                secrets: false,
                metrics: false,
                http_client: true,
                cli: false,
                filesystem: false,
                sockets: false,
            }),
            _ => None,
        }
    }
}

fn default_api_bind() -> String {
    "0.0.0.0:3669".to_string()
}

/// API server configuration (embedded in deploy/up flows)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ApiSpec {
    /// Enable the API server (default: true)
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Bind address (default: "0.0.0.0:3669")
    #[serde(default = "default_api_bind")]
    pub bind: String,
    /// JWT secret (reads `ZLAYER_JWT_SECRET` env var if not set)
    #[serde(default)]
    pub jwt_secret: Option<String>,
    /// Enable Swagger UI (default: true)
    #[serde(default = "default_true")]
    pub swagger: bool,
}

impl Default for ApiSpec {
    fn default() -> Self {
        Self {
            enabled: true,
            bind: default_api_bind(),
            jwt_secret: None,
            swagger: true,
        }
    }
}

/// Top-level deployment specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Validate)]
#[serde(deny_unknown_fields)]
pub struct DeploymentSpec {
    /// Spec version (must be "v1")
    #[validate(custom(function = "crate::spec::validate::validate_version_wrapper"))]
    pub version: String,

    /// Deployment name (used for overlays, DNS)
    #[validate(custom(function = "crate::spec::validate::validate_deployment_name_wrapper"))]
    pub deployment: String,

    /// Service definitions
    #[serde(default)]
    #[validate(nested)]
    pub services: HashMap<String, ServiceSpec>,

    /// External service definitions (proxy backends without containers)
    ///
    /// External services register static backend addresses with the proxy
    /// for host/path-based routing without starting any containers.
    /// Useful for proxying to services running outside of `ZLayer`
    /// (e.g., on other machines reachable via VPN).
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    #[validate(nested)]
    pub externals: HashMap<String, ExternalSpec>,

    /// Top-level tunnel definitions (not tied to service endpoints)
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub tunnels: HashMap<String, TunnelDefinition>,

    /// API server configuration (enabled by default)
    #[serde(default)]
    pub api: ApiSpec,
}

/// External service specification (proxy backend without a container)
///
/// Defines a service that is not managed by `ZLayer` but should be proxied
/// through `ZLayer`'s reverse proxy. The proxy registers static backend
/// addresses and routes traffic based on endpoint host/path matching.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct ExternalSpec {
    /// Static backend addresses (e.g., `["100.64.1.5:8096", "192.168.1.10:8096"]`)
    ///
    /// These are the upstream addresses the proxy will forward traffic to.
    /// At least one backend is required.
    #[validate(length(min = 1, message = "at least one backend address is required"))]
    pub backends: Vec<String>,

    /// Endpoint definitions (proxy bindings)
    ///
    /// Defines how public/internal traffic is routed to this external service.
    #[serde(default)]
    #[validate(nested)]
    pub endpoints: Vec<EndpointSpec>,

    /// Health check configuration
    ///
    /// When specified, the proxy will health-check backends and remove
    /// unhealthy ones from the rotation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub health: Option<HealthSpec>,
}

/// Top-level tunnel definition (not tied to a service endpoint)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct TunnelDefinition {
    /// Source node
    pub from: String,

    /// Destination node
    pub to: String,

    /// Local port on source
    pub local_port: u16,

    /// Remote port on destination
    pub remote_port: u16,

    /// Protocol (tcp/udp, defaults to tcp)
    #[serde(default)]
    pub protocol: TunnelProtocol,

    /// Exposure type (defaults to internal)
    #[serde(default)]
    pub expose: ExposeType,
}

/// Protocol for tunnel connections (tcp or udp only)
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum TunnelProtocol {
    #[default]
    Tcp,
    Udp,
}

/// Log output configuration for services and jobs.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct LogsConfig {
    /// Where to write logs: "disk" (default) or "memory"
    #[serde(default = "default_logs_destination")]
    pub destination: String,

    /// Maximum log size in bytes (default: 100MB)
    #[serde(default = "default_logs_max_size")]
    pub max_size_bytes: u64,

    /// Log retention in seconds (default: 7 days)
    #[serde(default = "default_logs_retention")]
    pub retention_secs: u64,
}

fn default_logs_destination() -> String {
    "disk".to_string()
}

fn default_logs_max_size() -> u64 {
    100 * 1024 * 1024 // 100MB
}

fn default_logs_retention() -> u64 {
    7 * 24 * 60 * 60 // 7 days
}

impl Default for LogsConfig {
    fn default() -> Self {
        Self {
            destination: default_logs_destination(),
            max_size_bytes: default_logs_max_size(),
            retention_secs: default_logs_retention(),
        }
    }
}

/// Per-service specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Validate)]
#[serde(deny_unknown_fields)]
pub struct ServiceSpec {
    /// Resource type (service, job, cron)
    #[serde(default = "default_resource_type")]
    pub rtype: ResourceType,

    /// Cron schedule expression (only for rtype: cron)
    /// Uses 7-field cron syntax: "sec min hour day-of-month month day-of-week year"
    /// Examples:
    ///   - "0 0 0 * * * *" (daily at midnight)
    ///   - "0 */5 * * * * *" (every 5 minutes)
    ///   - "0 0 12 * * MON-FRI *" (weekdays at noon)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    #[validate(custom(function = "crate::spec::validate::validate_schedule_wrapper"))]
    pub schedule: Option<String>,

    /// Container image specification
    #[validate(nested)]
    pub image: ImageSpec,

    /// Resource limits
    #[serde(default)]
    #[validate(nested)]
    pub resources: ResourcesSpec,

    /// Environment variables for the service
    ///
    /// Values can be:
    /// - Plain strings: `"value"`
    /// - Host env refs: `$E:VAR_NAME`
    /// - Secret refs: `$S:secret-name` or `$S:@service/secret-name`
    #[serde(default)]
    pub env: HashMap<String, String>,

    /// Command override (entrypoint, args, workdir)
    #[serde(default)]
    pub command: CommandSpec,

    /// Network configuration
    #[serde(default)]
    pub network: ServiceNetworkSpec,

    /// Endpoint definitions (proxy bindings)
    #[serde(default)]
    #[validate(nested)]
    pub endpoints: Vec<EndpointSpec>,

    /// Scaling configuration
    #[serde(default)]
    #[validate(custom(function = "crate::spec::validate::validate_scale_spec"))]
    pub scale: ScaleSpec,

    /// Dependency specifications
    #[serde(default)]
    pub depends: Vec<DependsSpec>,

    /// Health check configuration
    #[serde(default = "default_health")]
    pub health: HealthSpec,

    /// Init actions (pre-start lifecycle steps)
    #[serde(default)]
    pub init: InitSpec,

    /// Error handling policies
    #[serde(default)]
    pub errors: ErrorsSpec,

    /// Device passthrough (e.g., /dev/kvm for VMs)
    #[serde(default)]
    pub devices: Vec<DeviceSpec>,

    /// Storage mounts for the container
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub storage: Vec<StorageSpec>,

    /// Host-to-container port mappings (Docker's `-p host:container/proto`).
    ///
    /// Each entry publishes a container port on the host. When `host_port` is
    /// `None` (or zero), the daemon assigns an ephemeral host port.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub port_mappings: Vec<PortMapping>,

    /// Linux capabilities to add (e.g., `SYS_ADMIN`, `NET_ADMIN`)
    #[serde(default)]
    pub capabilities: Vec<String>,

    /// Run container in privileged mode (all capabilities + all devices)
    #[serde(default)]
    pub privileged: bool,

    /// Node allocation mode (shared, dedicated, exclusive)
    #[serde(default)]
    pub node_mode: NodeMode,

    /// Node selection constraints (required/preferred labels)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub node_selector: Option<NodeSelector>,

    /// Target platform for this service. When `None` (default), the service is
    /// eligible to run on any agent regardless of OS/architecture. When `Some`,
    /// the scheduler will only place replicas on agents whose platform matches.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub platform: Option<TargetPlatform>,

    /// Service type (standard, `wasm_http`, `wasm_plugin`, etc.)
    #[serde(default)]
    pub service_type: ServiceType,

    /// WASM configuration (used when `service_type` is any Wasm* variant)
    /// Also accepts the deprecated `wasm_http` key for backward compatibility.
    #[serde(default, skip_serializing_if = "Option::is_none", alias = "wasm_http")]
    pub wasm: Option<WasmConfig>,

    /// Log output configuration. If not set, uses platform defaults.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub logs: Option<LogsConfig>,

    /// Use host networking (container shares host network namespace)
    ///
    /// When true, the container will NOT get its own network namespace.
    /// This is set programmatically via the `--host-network` CLI flag, not in YAML specs.
    #[serde(skip)]
    pub host_network: bool,

    /// Container hostname (maps to Docker's `--hostname`).
    ///
    /// When set, the container's `/etc/hostname` and initial kernel hostname
    /// are configured to this value. Ignored when `host_network` is true
    /// (the container inherits the host's hostname).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hostname: Option<String>,

    /// Additional DNS servers for the container (maps to Docker's `--dns`).
    ///
    /// Each entry must be a plausible IPv4 or IPv6 address. Forwarded to the
    /// container runtime as resolver addresses ahead of the platform defaults.
    /// Ignored when `host_network` is true.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub dns: Vec<String>,

    /// Extra `hostname:ip` entries appended to `/etc/hosts` (maps to Docker's
    /// `--add-host`).
    ///
    /// Each entry must be in the form `"<hostname>:<ip>"`. The special literal
    /// `host-gateway` is accepted as the `<ip>` half (resolved by Docker /
    /// bollard to the host-visible gateway address, commonly used with
    /// `host.docker.internal:host-gateway`).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extra_hosts: Vec<String>,

    /// Container restart policy (Docker-style).
    ///
    /// Controls when the runtime should automatically restart the container
    /// after it exits. Maps to Docker's `HostConfig.RestartPolicy`. Named
    /// `ContainerRestartPolicy` to avoid colliding with `ZLayer`'s existing
    /// `PanicPolicy` (which controls post-panic behavior, not runtime-level
    /// restarts).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub restart_policy: Option<ContainerRestartPolicy>,
}

/// Command override specification (Section 5.5)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct CommandSpec {
    /// Override image ENTRYPOINT
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub entrypoint: Option<Vec<String>>,

    /// Override image CMD
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub args: Option<Vec<String>>,

    /// Override working directory
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workdir: Option<String>,
}

fn default_resource_type() -> ResourceType {
    ResourceType::Service
}

fn default_health() -> HealthSpec {
    HealthSpec {
        start_grace: Some(std::time::Duration::from_secs(5)),
        interval: None,
        timeout: None,
        retries: 3,
        check: HealthCheck::Tcp { port: 0 },
    }
}

/// Resource type - determines container lifecycle
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum ResourceType {
    /// Long-running container, receives traffic, load-balanced
    Service,
    /// Run-to-completion, triggered by endpoint/CLI/internal system
    Job,
    /// Scheduled run-to-completion, time-triggered
    Cron,
}

/// Container image specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct ImageSpec {
    /// Image name (e.g., "ghcr.io/org/api:latest")
    #[serde(with = "crate::image_ref_serde")]
    pub name: crate::ImageReference,

    /// When to pull the image
    #[serde(default = "default_pull_policy")]
    pub pull_policy: PullPolicy,
}

fn default_pull_policy() -> PullPolicy {
    PullPolicy::IfNotPresent
}

/// Image pull policy
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum PullPolicy {
    /// Always pull the image, even if cached
    Always,
    /// Resolve remote digest; pull and recreate when it differs from local/running
    Newer,
    /// Pull only if not present locally
    IfNotPresent,
    /// Never pull, use local image only
    Never,
}

/// Resolve the effective pull policy for a deploy/scale operation.
///
/// The serde default for `pull_policy` is `IfNotPresent` (preserved for
/// backwards compatibility). When the user has not opted out (i.e. the policy
/// is the default `IfNotPresent`) AND the image tag is `:latest` or unspecified,
/// we auto-upgrade to `Newer` so freshly-pushed `:latest` images get picked up
/// on redeploy. Users who explicitly want immutable behaviour on a `:latest`
/// tag can set `pull_policy: never`.
#[must_use]
pub fn effective_pull_policy(image: &crate::ImageReference, spec_policy: PullPolicy) -> PullPolicy {
    match spec_policy {
        PullPolicy::Always | PullPolicy::Never | PullPolicy::Newer => spec_policy,
        PullPolicy::IfNotPresent => {
            // Auto-upgrade IfNotPresent to Newer for :latest / no-tag images
            if image_is_latest_or_untagged(image) {
                PullPolicy::Newer
            } else {
                PullPolicy::IfNotPresent
            }
        }
    }
}

fn image_is_latest_or_untagged(image: &crate::ImageReference) -> bool {
    // `ImageReference` is `oci_spec::distribution::Reference`, which exposes a
    // clean `tag()` accessor returning `Option<&str>`. No tag, or tag "latest",
    // is treated as the rolling case.
    match image.tag() {
        None => true,
        Some(tag) => tag == "latest",
    }
}

/// Device passthrough specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct DeviceSpec {
    /// Host device path (e.g., /dev/kvm, /dev/net/tun)
    #[validate(length(min = 1, message = "device path cannot be empty"))]
    pub path: String,

    /// Allow read access
    #[serde(default = "default_true")]
    pub read: bool,

    /// Allow write access
    #[serde(default = "default_true")]
    pub write: bool,

    /// Allow mknod (create device nodes)
    #[serde(default)]
    pub mknod: bool,
}

fn default_true() -> bool {
    true
}

/// Storage mount specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields, tag = "type", rename_all = "snake_case")]
pub enum StorageSpec {
    /// Bind mount from host path to container
    Bind {
        source: String,
        target: String,
        #[serde(default)]
        readonly: bool,
    },
    /// Named persistent storage volume
    Named {
        name: String,
        target: String,
        #[serde(default)]
        readonly: bool,
        /// Performance tier (default: local, SQLite-safe)
        #[serde(default)]
        tier: StorageTier,
        /// Optional size limit (e.g., "1Gi", "512Mi")
        #[serde(default, skip_serializing_if = "Option::is_none")]
        size: Option<String>,
    },
    /// Anonymous storage (auto-named, container lifecycle)
    Anonymous {
        target: String,
        /// Performance tier (default: local)
        #[serde(default)]
        tier: StorageTier,
    },
    /// Memory-backed tmpfs mount
    Tmpfs {
        target: String,
        #[serde(default)]
        size: Option<String>,
        #[serde(default)]
        mode: Option<u32>,
    },
    /// S3-backed FUSE mount
    S3 {
        bucket: String,
        #[serde(default)]
        prefix: Option<String>,
        target: String,
        #[serde(default)]
        readonly: bool,
        #[serde(default)]
        endpoint: Option<String>,
        #[serde(default)]
        credentials: Option<String>,
    },
}

/// Resource limits (upper bounds, not reservations)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default, Validate)]
#[serde(deny_unknown_fields)]
pub struct ResourcesSpec {
    /// CPU limit (cores, e.g., 0.5, 1, 2)
    #[serde(default)]
    #[validate(custom(function = "crate::spec::validate::validate_cpu_option_wrapper"))]
    pub cpu: Option<f64>,

    /// Memory limit (e.g., "512Mi", "1Gi", "2Gi")
    #[serde(default)]
    #[validate(custom(function = "crate::spec::validate::validate_memory_option_wrapper"))]
    pub memory: Option<String>,

    /// GPU resource request
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub gpu: Option<GpuSpec>,
}

/// Scheduling policy for GPU workloads
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "kebab-case")]
pub enum SchedulingPolicy {
    /// Place as many replicas as possible; partial placement is acceptable (default)
    #[default]
    BestEffort,
    /// All replicas must be placed or none are; prevents partial GPU job deployment
    Gang,
    /// Spread replicas across nodes to maximize GPU distribution
    Spread,
}

/// GPU sharing mode controlling how GPU resources are multiplexed.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "kebab-case")]
pub enum GpuSharingMode {
    /// Whole GPU per container (default). No sharing.
    #[default]
    Exclusive,
    /// NVIDIA Multi-Process Service: concurrent GPU compute sharing.
    /// Multiple containers run GPU kernels simultaneously with hardware isolation.
    Mps,
    /// NVIDIA time-slicing: round-robin GPU access across containers.
    /// Lower overhead than MPS but no concurrent execution.
    TimeSlice,
}

/// Configuration for distributed GPU job coordination.
///
/// When enabled on a multi-replica GPU service, `ZLayer` injects standard
/// distributed training environment variables (`MASTER_ADDR`, `MASTER_PORT`,
/// `WORLD_SIZE`, `RANK`, `LOCAL_RANK`) so frameworks like `PyTorch`, `Horovod`,
/// and `DeepSpeed` can coordinate automatically.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct DistributedConfig {
    /// Communication backend: "nccl" (default), "gloo", or "mpi"
    #[serde(default = "default_dist_backend")]
    pub backend: String,
    /// Port for rank-0 master coordination (default: 29500)
    #[serde(default = "default_dist_port")]
    pub master_port: u16,
}

fn default_dist_backend() -> String {
    "nccl".to_string()
}

fn default_dist_port() -> u16 {
    29500
}

/// GPU resource specification
///
/// Supported vendors:
/// - `nvidia` - NVIDIA GPUs via NVIDIA Container Toolkit (default)
/// - `amd` - AMD GPUs via `ROCm` (/dev/kfd + /dev/dri/renderD*)
/// - `intel` - Intel GPUs via VAAPI/i915 (/dev/dri/renderD*)
/// - `apple` - Apple Silicon GPUs via Metal/MPS (macOS only)
///
/// Unknown vendors fall back to DRI render node passthrough.
///
/// ## GPU mode (macOS only)
///
/// When `vendor` is `"apple"`, the `mode` field controls how GPU access is provided:
/// - `"native"` -- Seatbelt sandbox with direct Metal/MPS access (lowest overhead)
/// - `"vm"` -- libkrun micro-VM with GPU forwarding (stronger isolation)
/// - `None` (default) -- Auto-select based on platform and vendor
///
/// On Linux, `mode` is ignored; GPU passthrough always uses device node binding.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct GpuSpec {
    /// Number of GPUs to request
    #[serde(default = "default_gpu_count")]
    pub count: u32,
    /// GPU vendor (`nvidia`, `amd`, `intel`, `apple`) - defaults to `nvidia`
    #[serde(default = "default_gpu_vendor")]
    pub vendor: String,
    /// GPU access mode (macOS only): `"native"`, `"vm"`, or `None` for auto-select
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mode: Option<String>,
    /// Pin to a specific GPU model (e.g. "A100", "H100").
    /// Substring match against detected GPU model names.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model: Option<String>,
    /// Scheduling policy for GPU workloads.
    /// - `best-effort` (default): place what fits
    /// - `gang`: all-or-nothing for distributed jobs
    /// - `spread`: distribute across nodes
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scheduling: Option<SchedulingPolicy>,
    /// Distributed GPU job coordination.
    /// When set, injects `MASTER_ADDR`, `WORLD_SIZE`, `RANK`, `LOCAL_RANK` env vars.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub distributed: Option<DistributedConfig>,
    /// GPU sharing mode: exclusive (default), mps, or time-slice.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sharing: Option<GpuSharingMode>,
}

fn default_gpu_count() -> u32 {
    1
}

fn default_gpu_vendor() -> String {
    "nvidia".to_string()
}

/// Per-service network configuration (overlay + join policy).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[derive(Default)]
pub struct ServiceNetworkSpec {
    /// Overlay network configuration
    #[serde(default)]
    pub overlays: OverlayConfig,

    /// Join policy (who can join this service)
    #[serde(default)]
    pub join: JoinPolicy,
}

/// Overlay network configuration
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct OverlayConfig {
    /// Service-scoped overlay (service replicas only)
    #[serde(default)]
    pub service: OverlaySettings,

    /// Global overlay (all services in deployment)
    #[serde(default)]
    pub global: OverlaySettings,
}

impl Default for OverlayConfig {
    fn default() -> Self {
        Self {
            service: OverlaySettings {
                enabled: true,
                encrypted: true,
                isolated: true,
            },
            global: OverlaySettings {
                enabled: true,
                encrypted: true,
                isolated: false,
            },
        }
    }
}

/// Overlay network settings
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct OverlaySettings {
    /// Enable this overlay
    #[serde(default = "default_enabled")]
    pub enabled: bool,

    /// Use encryption
    #[serde(default = "default_encrypted")]
    pub encrypted: bool,

    /// Isolate from other services/groups
    #[serde(default)]
    pub isolated: bool,
}

fn default_enabled() -> bool {
    true
}

fn default_encrypted() -> bool {
    true
}

/// Join policy - controls who can join a service
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct JoinPolicy {
    /// Join mode
    #[serde(default = "default_join_mode")]
    pub mode: JoinMode,

    /// Scope of join
    #[serde(default = "default_join_scope")]
    pub scope: JoinScope,
}

impl Default for JoinPolicy {
    fn default() -> Self {
        Self {
            mode: default_join_mode(),
            scope: default_join_scope(),
        }
    }
}

fn default_join_mode() -> JoinMode {
    JoinMode::Token
}

fn default_join_scope() -> JoinScope {
    JoinScope::Service
}

/// Join mode
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum JoinMode {
    /// Any trusted node in deployment can self-enroll
    Open,
    /// Requires a join key (recommended)
    Token,
    /// Only control-plane/scheduler can place replicas
    Closed,
}

/// Join scope
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum JoinScope {
    /// Join this specific service
    Service,
    /// Join all services in deployment
    Global,
}

/// Endpoint specification (proxy binding)
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Validate)]
#[serde(deny_unknown_fields)]
pub struct EndpointSpec {
    /// Endpoint name (for routing)
    #[validate(length(min = 1, message = "endpoint name cannot be empty"))]
    pub name: String,

    /// Protocol
    pub protocol: Protocol,

    /// Proxy listen port (external-facing port)
    #[validate(custom(function = "crate::spec::validate::validate_port_wrapper"))]
    pub port: u16,

    /// Container port the service actually listens on.
    /// Defaults to `port` when not specified.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target_port: Option<u16>,

    /// URL path prefix (for http/https/websocket)
    pub path: Option<String>,

    /// Host pattern for routing (e.g. "api.example.com" or "*.example.com").
    /// `None` means match any host.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub host: Option<String>,

    /// Exposure type
    #[serde(default = "default_expose")]
    pub expose: ExposeType,

    /// Optional stream (L4) proxy configuration
    /// Only applicable when protocol is tcp or udp
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stream: Option<StreamEndpointConfig>,

    /// Optional tunnel configuration for this endpoint
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tunnel: Option<EndpointTunnelConfig>,
}

impl EndpointSpec {
    /// Returns the port the container actually listens on.
    /// Falls back to `port` when `target_port` is not specified.
    #[must_use]
    pub fn target_port(&self) -> u16 {
        self.target_port.unwrap_or(self.port)
    }
}

/// Tunnel configuration for an endpoint
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct EndpointTunnelConfig {
    /// Enable tunneling for this endpoint
    #[serde(default)]
    pub enabled: bool,

    /// Source node name (defaults to service's node)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,

    /// Destination node name (defaults to cluster ingress)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub to: Option<String>,

    /// Remote port to expose (0 = auto-assign)
    #[serde(default)]
    pub remote_port: u16,

    /// Override exposure for tunnel (public/internal)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expose: Option<ExposeType>,

    /// On-demand access configuration
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub access: Option<TunnelAccessConfig>,
}

/// On-demand access settings for `zlayer tunnel access`
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct TunnelAccessConfig {
    /// Allow on-demand access via CLI
    #[serde(default)]
    pub enabled: bool,

    /// Maximum session duration (e.g., "4h", "30m")
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_ttl: Option<String>,

    /// Log all access sessions
    #[serde(default)]
    pub audit: bool,
}

fn default_expose() -> ExposeType {
    ExposeType::Internal
}

/// Protocol type
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum Protocol {
    Http,
    Https,
    Tcp,
    Udp,
    Websocket,
}

/// Exposure type
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum ExposeType {
    Public,
    #[default]
    Internal,
}

/// Stream (L4) proxy configuration for TCP/UDP endpoints
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(deny_unknown_fields)]
pub struct StreamEndpointConfig {
    /// Enable TLS termination for TCP (auto-provision cert)
    #[serde(default)]
    pub tls: bool,

    /// Enable PROXY protocol for passing client IP
    #[serde(default)]
    pub proxy_protocol: bool,

    /// Custom session timeout for UDP (default: 60s)
    /// Format: duration string like "60s", "5m"
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_timeout: Option<String>,

    /// Health check configuration for L4
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub health_check: Option<StreamHealthCheck>,
}

/// Health check types for stream (L4) endpoints
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum StreamHealthCheck {
    /// TCP connect check - verifies port is accepting connections
    TcpConnect,
    /// UDP probe - sends request and optionally validates response
    UdpProbe {
        /// Request payload to send (can use hex escapes like \\xFF)
        request: String,
        /// Expected response pattern (optional regex)
        #[serde(default, skip_serializing_if = "Option::is_none")]
        expect: Option<String>,
    },
}

/// Scaling configuration
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "mode", rename_all = "lowercase", deny_unknown_fields)]
pub enum ScaleSpec {
    /// Adaptive scaling with metrics
    #[serde(rename = "adaptive")]
    Adaptive {
        /// Minimum replicas
        min: u32,

        /// Maximum replicas
        max: u32,

        /// Cooldown period between scale events
        #[serde(default, with = "duration::option")]
        cooldown: Option<std::time::Duration>,

        /// Target metrics for scaling
        #[serde(default)]
        targets: ScaleTargets,
    },

    /// Fixed number of replicas
    #[serde(rename = "fixed")]
    Fixed { replicas: u32 },

    /// Manual scaling (no automatic scaling)
    #[serde(rename = "manual")]
    Manual,
}

impl Default for ScaleSpec {
    fn default() -> Self {
        Self::Adaptive {
            min: 1,
            max: 10,
            cooldown: Some(std::time::Duration::from_secs(30)),
            targets: ScaleTargets::default(),
        }
    }
}

/// Target metrics for adaptive scaling
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[derive(Default)]
pub struct ScaleTargets {
    /// CPU percentage threshold (0-100)
    #[serde(default)]
    pub cpu: Option<u8>,

    /// Memory percentage threshold (0-100)
    #[serde(default)]
    pub memory: Option<u8>,

    /// Requests per second threshold
    #[serde(default)]
    pub rps: Option<u32>,
}

/// Dependency specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct DependsSpec {
    /// Service name to depend on
    pub service: String,

    /// Condition for dependency
    #[serde(default = "default_condition")]
    pub condition: DependencyCondition,

    /// Maximum time to wait
    #[serde(default = "default_timeout", with = "duration::option")]
    pub timeout: Option<std::time::Duration>,

    /// Action on timeout
    #[serde(default = "default_on_timeout")]
    pub on_timeout: TimeoutAction,
}

fn default_condition() -> DependencyCondition {
    DependencyCondition::Healthy
}

#[allow(clippy::unnecessary_wraps)]
fn default_timeout() -> Option<std::time::Duration> {
    Some(std::time::Duration::from_secs(300))
}

fn default_on_timeout() -> TimeoutAction {
    TimeoutAction::Fail
}

/// Dependency condition
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum DependencyCondition {
    /// Container process exists
    Started,
    /// Health check passes
    Healthy,
    /// Service is available for routing
    Ready,
}

/// Timeout action
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum TimeoutAction {
    Fail,
    Warn,
    Continue,
}

/// Health check specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct HealthSpec {
    /// Grace period before first check
    #[serde(default, with = "duration::option")]
    pub start_grace: Option<std::time::Duration>,

    /// Interval between checks
    #[serde(default, with = "duration::option")]
    pub interval: Option<std::time::Duration>,

    /// Timeout per check
    #[serde(default, with = "duration::option")]
    pub timeout: Option<std::time::Duration>,

    /// Number of retries before marking unhealthy
    #[serde(default = "default_retries")]
    pub retries: u32,

    /// Health check type and parameters
    pub check: HealthCheck,
}

fn default_retries() -> u32 {
    3
}

/// Health check type
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum HealthCheck {
    /// TCP port check
    Tcp {
        /// Port to check (0 = use first endpoint)
        port: u16,
    },

    /// HTTP check
    Http {
        /// URL to check
        url: String,
        /// Expected status code
        #[serde(default = "default_expect_status")]
        expect_status: u16,
    },

    /// Command check
    Command {
        /// Command to run
        command: String,
    },
}

fn default_expect_status() -> u16 {
    200
}

/// Init actions specification
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[derive(Default)]
pub struct InitSpec {
    /// Init steps to run before container starts
    #[serde(default)]
    pub steps: Vec<InitStep>,
}

/// Init action step
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct InitStep {
    /// Step identifier
    pub id: String,

    /// Action to perform (e.g., "`init.wait_tcp`")
    pub uses: String,

    /// Parameters for the action
    #[serde(default)]
    pub with: InitParams,

    /// Number of retries
    #[serde(default)]
    pub retry: Option<u32>,

    /// Maximum time for this step
    #[serde(default, with = "duration::option")]
    pub timeout: Option<std::time::Duration>,

    /// Action on failure
    #[serde(default = "default_on_failure")]
    pub on_failure: FailureAction,
}

fn default_on_failure() -> FailureAction {
    FailureAction::Fail
}

/// Init action parameters
pub type InitParams = std::collections::HashMap<String, serde_json::Value>;

/// Failure action for init steps
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum FailureAction {
    Fail,
    Warn,
    Continue,
}

/// Error handling policies
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
#[derive(Default)]
pub struct ErrorsSpec {
    /// Init failure policy
    #[serde(default)]
    pub on_init_failure: InitFailurePolicy,

    /// Panic/restart policy
    #[serde(default)]
    pub on_panic: PanicPolicy,
}

/// Init failure policy
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct InitFailurePolicy {
    #[serde(default = "default_init_action")]
    pub action: InitFailureAction,
}

impl Default for InitFailurePolicy {
    fn default() -> Self {
        Self {
            action: default_init_action(),
        }
    }
}

fn default_init_action() -> InitFailureAction {
    InitFailureAction::Fail
}

/// Init failure action
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum InitFailureAction {
    Fail,
    Restart,
    Backoff,
}

/// Panic policy
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PanicPolicy {
    #[serde(default = "default_panic_action")]
    pub action: PanicAction,
}

impl Default for PanicPolicy {
    fn default() -> Self {
        Self {
            action: default_panic_action(),
        }
    }
}

fn default_panic_action() -> PanicAction {
    PanicAction::Restart
}

/// Panic action
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum PanicAction {
    Restart,
    Shutdown,
    Isolate,
}

// ==========================================================================
// Network / Access Control types
// ==========================================================================

/// A network policy defines an access control group with membership rules
/// and service access policies.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Default)]
pub struct NetworkPolicySpec {
    /// Unique network name.
    pub name: String,

    /// Human-readable description.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// CIDR ranges that belong to this network (e.g., "10.200.0.0/16", "192.168.1.0/24").
    #[serde(default)]
    pub cidrs: Vec<String>,

    /// Named members (users, groups, nodes) of this network.
    #[serde(default)]
    pub members: Vec<NetworkMember>,

    /// Access rules defining which services this network can reach.
    #[serde(default)]
    pub access_rules: Vec<AccessRule>,
}

/// A member of a network.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct NetworkMember {
    /// Member identifier (username, group name, node ID, or CIDR).
    pub name: String,
    /// Type of member.
    #[serde(default)]
    pub kind: MemberKind,
}

/// Type of network member.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum MemberKind {
    /// An individual user identity.
    #[default]
    User,
    /// A group of users.
    Group,
    /// A specific cluster node.
    Node,
    /// A CIDR range (redundant with NetworkPolicySpec.cidrs but allows per-member CIDR).
    Cidr,
}

/// An access rule determining what a network can reach.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct AccessRule {
    /// Target service name, or "*" for all services.
    #[serde(default = "wildcard")]
    pub service: String,

    /// Target deployment name, or "*" for all deployments.
    #[serde(default = "wildcard")]
    pub deployment: String,

    /// Specific ports allowed. None means all ports.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ports: Option<Vec<u16>>,

    /// Whether to allow or deny access.
    #[serde(default)]
    pub action: AccessAction,
}

fn wildcard() -> String {
    "*".to_string()
}

/// Access control action.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum AccessAction {
    /// Allow access (default).
    #[default]
    Allow,
    /// Deny access.
    Deny,
}

// ==========================================================================
// Container bridge / overlay network types (Docker-compatible)
// ==========================================================================
//
// These types model user-defined bridge or overlay networks that standalone
// containers can attach to — the Docker-style "docker network create" model.
// They are intentionally named `BridgeNetwork*` to avoid colliding with the
// CIDR-ACL `NetworkPolicySpec` types above, which model a completely
// different concept (access-control groups).

/// A user-defined bridge or overlay network that containers can attach to.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
pub struct BridgeNetwork {
    /// Opaque server-generated identifier (UUID v4).
    pub id: String,

    /// Human-readable, unique name (must match `^[a-z0-9][a-z0-9_-]{0,63}$`).
    pub name: String,

    /// Driver backing the network (bridge vs. overlay).
    #[serde(default)]
    pub driver: BridgeNetworkDriver,

    /// IPv4/IPv6 subnet in CIDR notation (e.g. `"10.240.0.0/24"`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub subnet: Option<String>,

    /// Arbitrary key/value labels for filtering and grouping.
    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
    pub labels: HashMap<String, String>,

    /// If true, containers attached to this network cannot reach the outside
    /// world — only other containers on the same network.
    #[serde(default)]
    pub internal: bool,

    /// Creation timestamp (UTC, RFC 3339).
    #[schema(value_type = String, format = "date-time")]
    pub created_at: chrono::DateTime<chrono::Utc>,
}

/// Backing driver for a [`BridgeNetwork`].
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default, utoipa::ToSchema)]
#[serde(rename_all = "lowercase")]
pub enum BridgeNetworkDriver {
    /// Linux bridge on the local host (single-host, default).
    #[default]
    Bridge,
    /// Overlay network spanning multiple hosts.
    Overlay,
}

/// A container attached to a [`BridgeNetwork`].
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
pub struct BridgeNetworkAttachment {
    /// Runtime-provided container id.
    pub container_id: String,

    /// Container name, if known.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub container_name: Option<String>,

    /// DNS aliases the container can be reached by on this network.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub aliases: Vec<String>,

    /// Assigned IPv4 address on the network (if any).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ipv4: Option<String>,
}

// ==========================================================================
// Registry auth (inline, not persisted) — §3.10 of ZLAYER_SDK_FIXES.md
// ==========================================================================
//
// Inline credentials a client can attach to a single pull or container-create
// request without first POSTing them to `/api/v1/credentials/registry`. The
// daemon uses them exactly once — they are never logged, never persisted, and
// never echoed back on a response.
//
// For requests that instead want to reuse an already-stored credential, the
// `CreateContainerRequest` / `PullImageRequest` DTOs also accept a
// `registry_credential_id` pointing at the `RegistryCredentialStore`. Inline
// `RegistryAuth` takes precedence when both are provided.

/// Inline Docker/OCI registry credentials attached to a single pull request.
///
/// Prefer persistent credentials via `/api/v1/credentials/registry` for
/// long-lived services. Use this inline form for one-off pulls (e.g. CI
/// runners fetching a private image for a single job) where persisting a
/// credential is undesirable.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
pub struct RegistryAuth {
    /// Username for the registry (for basic auth) or a placeholder
    /// identifier when `auth_type == Token`.
    pub username: String,
    /// Password or bearer token. **Never** logged or returned on any
    /// response — consumed once and dropped.
    pub password: String,
    /// Which authentication scheme to use against the registry.
    #[serde(default = "default_registry_auth_type")]
    pub auth_type: RegistryAuthType,
}

/// Authentication scheme for a [`RegistryAuth`].
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default, utoipa::ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum RegistryAuthType {
    /// HTTP Basic authentication (username + password). Default.
    #[default]
    Basic,
    /// Bearer token authentication. `password` carries the token; `username`
    /// is typically a placeholder such as `"oauth2accesstoken"` or `"<token>"`.
    Token,
}

/// Serde default for [`RegistryAuth::auth_type`]. Kept as a free function so
/// `#[serde(default = "...")]` can reference it.
#[must_use]
pub fn default_registry_auth_type() -> RegistryAuthType {
    RegistryAuthType::Basic
}

// ==========================================================================
// Container restart policy (Docker-style) — §3.4 of ZLAYER_SDK_FIXES.md
// ==========================================================================
//
// Named `ContainerRestartPolicy` / `ContainerRestartKind` rather than
// `RestartPolicy` / `RestartKind` to avoid colliding with ZLayer's existing
// `PanicPolicy`/`PanicAction` types and to make the runtime-level (as opposed
// to panic-driven) nature of this policy explicit.

/// Container-runtime-level restart policy.
///
/// Maps onto Docker's `HostConfig.RestartPolicy`. Distinct from
/// [`PanicPolicy`], which governs what `ZLayer` does in response to an
/// application panic (it does not set a Docker restart policy).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub struct ContainerRestartPolicy {
    /// Which restart policy to apply.
    pub kind: ContainerRestartKind,

    /// For `on_failure` only: maximum number of restart attempts before
    /// giving up. Ignored by other kinds. `None` means "retry forever".
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_attempts: Option<u32>,

    /// Humantime-formatted delay between restarts (e.g. `"500ms"`,
    /// `"2s"`). Accepted for forward-compatibility but currently ignored
    /// by the Docker backend: bollard's `RestartPolicy` has no per-kind
    /// delay field. When set, the runtime emits a warning.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub delay: Option<String>,
}

/// Which flavor of container restart policy to apply.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum ContainerRestartKind {
    /// Never restart (Docker's `"no"`).
    No,
    /// Always restart (Docker's `"always"`).
    Always,
    /// Restart unless the user explicitly stopped the container
    /// (Docker's `"unless-stopped"`).
    UnlessStopped,
    /// Restart only when the container exits with a non-zero code
    /// (Docker's `"on-failure"`). Respects `max_attempts`.
    OnFailure,
}

// ==========================================================================
// Port mappings (Docker-style container port publishing)
// ==========================================================================

/// Transport protocol for a published container port.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum PortProtocol {
    /// TCP (default).
    Tcp,
    /// UDP.
    Udp,
}

impl Default for PortProtocol {
    fn default() -> Self {
        default_port_protocol()
    }
}

impl PortProtocol {
    /// Return the lowercase string form Docker uses in port-binding keys
    /// (e.g. `"tcp"` or `"udp"`).
    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            PortProtocol::Tcp => "tcp",
            PortProtocol::Udp => "udp",
        }
    }
}

fn default_port_protocol() -> PortProtocol {
    PortProtocol::Tcp
}

fn default_host_ip() -> String {
    "0.0.0.0".to_string()
}

/// A single host-to-container port publish rule (Docker's `-p`).
///
/// When `host_port` is `None` (or explicitly `Some(0)`), the container runtime
/// assigns an ephemeral host port. `host_ip` defaults to `"0.0.0.0"` to bind
/// on all interfaces.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, utoipa::ToSchema)]
#[serde(rename_all = "snake_case")]
pub struct PortMapping {
    /// Host port. `None` (or zero) means "assign an ephemeral port".
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub host_port: Option<u16>,
    /// Container-side port.
    pub container_port: u16,
    /// Transport protocol (defaults to TCP).
    #[serde(default = "default_port_protocol")]
    pub protocol: PortProtocol,
    /// Host interface to bind on. Defaults to `"0.0.0.0"` (all interfaces).
    #[serde(default = "default_host_ip", skip_serializing_if = "String::is_empty")]
    pub host_ip: String,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn port_mapping_defaults_via_serde() {
        // Minimal JSON: only container_port. host_port omitted, protocol defaults
        // to "tcp", host_ip defaults to "0.0.0.0".
        let json = r#"{"container_port": 8080}"#;
        let m: PortMapping = serde_json::from_str(json).expect("parse minimal PortMapping");
        assert_eq!(m.container_port, 8080);
        assert_eq!(m.host_port, None);
        assert_eq!(m.protocol, PortProtocol::Tcp);
        assert_eq!(m.host_ip, "0.0.0.0");
    }

    #[test]
    fn port_mapping_skips_none_host_port_and_empty_host_ip() {
        let m = PortMapping {
            host_port: None,
            container_port: 443,
            protocol: PortProtocol::Tcp,
            host_ip: String::new(),
        };
        let s = serde_json::to_string(&m).expect("serialize");
        // host_port = None should be skipped, host_ip = "" should be skipped.
        assert!(!s.contains("host_port"), "host_port should be skipped: {s}");
        assert!(!s.contains("host_ip"), "host_ip should be skipped: {s}");
        assert!(s.contains("\"container_port\":443"));
        assert!(s.contains("\"protocol\":\"tcp\""));
    }

    #[test]
    fn test_parse_simple_spec() {
        let yaml = r"
version: v1
deployment: test
services:
  hello:
    rtype: service
    image:
      name: hello-world:latest
    endpoints:
      - name: http
        protocol: http
        port: 8080
        expose: public
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.version, "v1");
        assert_eq!(spec.deployment, "test");
        assert!(spec.services.contains_key("hello"));
    }

    #[test]
    fn test_parse_duration() {
        let yaml = r"
version: v1
deployment: test
services:
  test:
    rtype: service
    image:
      name: test:latest
    health:
      timeout: 30s
      interval: 1m
      start_grace: 5s
      check:
        type: tcp
        port: 8080
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let health = &spec.services["test"].health;
        assert_eq!(health.timeout, Some(std::time::Duration::from_secs(30)));
        assert_eq!(health.interval, Some(std::time::Duration::from_secs(60)));
        assert_eq!(health.start_grace, Some(std::time::Duration::from_secs(5)));
        match &health.check {
            HealthCheck::Tcp { port } => assert_eq!(*port, 8080),
            _ => panic!("Expected TCP health check"),
        }
    }

    #[test]
    fn test_parse_adaptive_scale() {
        let yaml = r"
version: v1
deployment: test
services:
  test:
    rtype: service
    image:
      name: test:latest
    scale:
      mode: adaptive
      min: 2
      max: 10
      cooldown: 15s
      targets:
        cpu: 70
        rps: 800
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let scale = &spec.services["test"].scale;
        match scale {
            ScaleSpec::Adaptive {
                min,
                max,
                cooldown,
                targets,
            } => {
                assert_eq!(*min, 2);
                assert_eq!(*max, 10);
                assert_eq!(*cooldown, Some(std::time::Duration::from_secs(15)));
                assert_eq!(targets.cpu, Some(70));
                assert_eq!(targets.rps, Some(800));
            }
            _ => panic!("Expected Adaptive scale mode"),
        }
    }

    #[test]
    fn test_node_mode_default() {
        let yaml = r"
version: v1
deployment: test
services:
  hello:
    rtype: service
    image:
      name: hello-world:latest
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.services["hello"].node_mode, NodeMode::Shared);
        assert!(spec.services["hello"].node_selector.is_none());
    }

    #[test]
    fn test_node_mode_dedicated() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    rtype: service
    image:
      name: api:latest
    node_mode: dedicated
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.services["api"].node_mode, NodeMode::Dedicated);
    }

    #[test]
    fn test_node_mode_exclusive() {
        let yaml = r"
version: v1
deployment: test
services:
  database:
    rtype: service
    image:
      name: postgres:15
    node_mode: exclusive
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.services["database"].node_mode, NodeMode::Exclusive);
    }

    #[test]
    fn test_node_selector_with_labels() {
        let yaml = r#"
version: v1
deployment: test
services:
  ml-worker:
    rtype: service
    image:
      name: ml-worker:latest
    node_mode: dedicated
    node_selector:
      labels:
        gpu: "true"
        zone: us-east
      prefer_labels:
        storage: ssd
"#;

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let service = &spec.services["ml-worker"];
        assert_eq!(service.node_mode, NodeMode::Dedicated);

        let selector = service.node_selector.as_ref().unwrap();
        assert_eq!(selector.labels.get("gpu"), Some(&"true".to_string()));
        assert_eq!(selector.labels.get("zone"), Some(&"us-east".to_string()));
        assert_eq!(
            selector.prefer_labels.get("storage"),
            Some(&"ssd".to_string())
        );
    }

    #[test]
    fn test_node_mode_serialization_roundtrip() {
        use serde_json;

        // Test all variants serialize/deserialize correctly
        let modes = [NodeMode::Shared, NodeMode::Dedicated, NodeMode::Exclusive];
        let expected_json = ["\"shared\"", "\"dedicated\"", "\"exclusive\""];

        for (mode, expected) in modes.iter().zip(expected_json.iter()) {
            let json = serde_json::to_string(mode).unwrap();
            assert_eq!(&json, *expected, "Serialization failed for {mode:?}");

            let deserialized: NodeMode = serde_json::from_str(&json).unwrap();
            assert_eq!(deserialized, *mode, "Roundtrip failed for {mode:?}");
        }
    }

    #[test]
    fn test_node_selector_empty() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    rtype: service
    image:
      name: api:latest
    node_selector:
      labels: {}
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let selector = spec.services["api"].node_selector.as_ref().unwrap();
        assert!(selector.labels.is_empty());
        assert!(selector.prefer_labels.is_empty());
    }

    #[test]
    fn test_mixed_node_modes_in_deployment() {
        let yaml = r"
version: v1
deployment: test
services:
  redis:
    rtype: service
    image:
      name: redis:alpine
    # Default shared mode
  api:
    rtype: service
    image:
      name: api:latest
    node_mode: dedicated
  database:
    rtype: service
    image:
      name: postgres:15
    node_mode: exclusive
    node_selector:
      labels:
        storage: ssd
";

        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.services["redis"].node_mode, NodeMode::Shared);
        assert_eq!(spec.services["api"].node_mode, NodeMode::Dedicated);
        assert_eq!(spec.services["database"].node_mode, NodeMode::Exclusive);

        let db_selector = spec.services["database"].node_selector.as_ref().unwrap();
        assert_eq!(db_selector.labels.get("storage"), Some(&"ssd".to_string()));
    }

    #[test]
    fn test_storage_bind_mount() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: bind
        source: /host/data
        target: /app/data
        readonly: true
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        assert_eq!(storage.len(), 1);
        match &storage[0] {
            StorageSpec::Bind {
                source,
                target,
                readonly,
            } => {
                assert_eq!(source, "/host/data");
                assert_eq!(target, "/app/data");
                assert!(*readonly);
            }
            _ => panic!("Expected Bind storage"),
        }
    }

    #[test]
    fn test_storage_named_with_tier() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: named
        name: my-data
        target: /app/data
        tier: cached
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        match &storage[0] {
            StorageSpec::Named {
                name, target, tier, ..
            } => {
                assert_eq!(name, "my-data");
                assert_eq!(target, "/app/data");
                assert_eq!(*tier, StorageTier::Cached);
            }
            _ => panic!("Expected Named storage"),
        }
    }

    #[test]
    fn test_storage_anonymous() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: anonymous
        target: /app/cache
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        match &storage[0] {
            StorageSpec::Anonymous { target, tier } => {
                assert_eq!(target, "/app/cache");
                assert_eq!(*tier, StorageTier::Local); // default
            }
            _ => panic!("Expected Anonymous storage"),
        }
    }

    #[test]
    fn test_storage_tmpfs() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: tmpfs
        target: /app/tmp
        size: 256Mi
        mode: 1777
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        match &storage[0] {
            StorageSpec::Tmpfs { target, size, mode } => {
                assert_eq!(target, "/app/tmp");
                assert_eq!(size.as_deref(), Some("256Mi"));
                assert_eq!(*mode, Some(1777));
            }
            _ => panic!("Expected Tmpfs storage"),
        }
    }

    #[test]
    fn test_storage_s3() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: s3
        bucket: my-bucket
        prefix: models/
        target: /app/models
        readonly: true
        endpoint: https://s3.us-west-2.amazonaws.com
        credentials: aws-creds
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        match &storage[0] {
            StorageSpec::S3 {
                bucket,
                prefix,
                target,
                readonly,
                endpoint,
                credentials,
            } => {
                assert_eq!(bucket, "my-bucket");
                assert_eq!(prefix.as_deref(), Some("models/"));
                assert_eq!(target, "/app/models");
                assert!(*readonly);
                assert_eq!(
                    endpoint.as_deref(),
                    Some("https://s3.us-west-2.amazonaws.com")
                );
                assert_eq!(credentials.as_deref(), Some("aws-creds"));
            }
            _ => panic!("Expected S3 storage"),
        }
    }

    #[test]
    fn test_storage_multiple_types() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: bind
        source: /etc/config
        target: /app/config
        readonly: true
      - type: named
        name: app-data
        target: /app/data
      - type: tmpfs
        target: /app/tmp
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let storage = &spec.services["app"].storage;
        assert_eq!(storage.len(), 3);
        assert!(matches!(&storage[0], StorageSpec::Bind { .. }));
        assert!(matches!(&storage[1], StorageSpec::Named { .. }));
        assert!(matches!(&storage[2], StorageSpec::Tmpfs { .. }));
    }

    #[test]
    fn test_storage_tier_default() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    image:
      name: app:latest
    storage:
      - type: named
        name: data
        target: /data
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        match &spec.services["app"].storage[0] {
            StorageSpec::Named { tier, .. } => {
                assert_eq!(*tier, StorageTier::Local); // default should be Local
            }
            _ => panic!("Expected Named storage"),
        }
    }

    // ==========================================================================
    // Tunnel configuration tests
    // ==========================================================================

    #[test]
    fn test_endpoint_tunnel_config_basic() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    image:
      name: api:latest
    endpoints:
      - name: http
        protocol: http
        port: 8080
        tunnel:
          enabled: true
          remote_port: 8080
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let endpoint = &spec.services["api"].endpoints[0];
        let tunnel = endpoint.tunnel.as_ref().unwrap();
        assert!(tunnel.enabled);
        assert_eq!(tunnel.remote_port, 8080);
        assert!(tunnel.from.is_none());
        assert!(tunnel.to.is_none());
    }

    #[test]
    fn test_endpoint_tunnel_config_full() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    image:
      name: api:latest
    endpoints:
      - name: http
        protocol: http
        port: 8080
        tunnel:
          enabled: true
          from: node-1
          to: ingress-node
          remote_port: 9000
          expose: public
          access:
            enabled: true
            max_ttl: 4h
            audit: true
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let endpoint = &spec.services["api"].endpoints[0];
        let tunnel = endpoint.tunnel.as_ref().unwrap();
        assert!(tunnel.enabled);
        assert_eq!(tunnel.from, Some("node-1".to_string()));
        assert_eq!(tunnel.to, Some("ingress-node".to_string()));
        assert_eq!(tunnel.remote_port, 9000);
        assert_eq!(tunnel.expose, Some(ExposeType::Public));

        let access = tunnel.access.as_ref().unwrap();
        assert!(access.enabled);
        assert_eq!(access.max_ttl, Some("4h".to_string()));
        assert!(access.audit);
    }

    #[test]
    fn test_top_level_tunnel_definition() {
        let yaml = r"
version: v1
deployment: test
services: {}
tunnels:
  db-tunnel:
    from: app-node
    to: db-node
    local_port: 5432
    remote_port: 5432
    protocol: tcp
    expose: internal
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let tunnel = spec.tunnels.get("db-tunnel").unwrap();
        assert_eq!(tunnel.from, "app-node");
        assert_eq!(tunnel.to, "db-node");
        assert_eq!(tunnel.local_port, 5432);
        assert_eq!(tunnel.remote_port, 5432);
        assert_eq!(tunnel.protocol, TunnelProtocol::Tcp);
        assert_eq!(tunnel.expose, ExposeType::Internal);
    }

    #[test]
    fn test_top_level_tunnel_defaults() {
        let yaml = r"
version: v1
deployment: test
services: {}
tunnels:
  simple-tunnel:
    from: node-a
    to: node-b
    local_port: 3000
    remote_port: 3000
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let tunnel = spec.tunnels.get("simple-tunnel").unwrap();
        assert_eq!(tunnel.protocol, TunnelProtocol::Tcp); // default
        assert_eq!(tunnel.expose, ExposeType::Internal); // default
    }

    #[test]
    fn test_tunnel_protocol_udp() {
        let yaml = r"
version: v1
deployment: test
services: {}
tunnels:
  udp-tunnel:
    from: node-a
    to: node-b
    local_port: 5353
    remote_port: 5353
    protocol: udp
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let tunnel = spec.tunnels.get("udp-tunnel").unwrap();
        assert_eq!(tunnel.protocol, TunnelProtocol::Udp);
    }

    #[test]
    fn test_endpoint_without_tunnel() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    image:
      name: api:latest
    endpoints:
      - name: http
        protocol: http
        port: 8080
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        let endpoint = &spec.services["api"].endpoints[0];
        assert!(endpoint.tunnel.is_none());
    }

    #[test]
    fn test_deployment_without_tunnels() {
        let yaml = r"
version: v1
deployment: test
services:
  api:
    image:
      name: api:latest
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert!(spec.tunnels.is_empty());
    }

    // ==========================================================================
    // ApiSpec tests
    // ==========================================================================

    #[test]
    fn test_spec_without_api_block_uses_defaults() {
        let yaml = r"
version: v1
deployment: test
services:
  hello:
    image:
      name: hello-world:latest
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert!(spec.api.enabled);
        assert_eq!(spec.api.bind, "0.0.0.0:3669");
        assert!(spec.api.jwt_secret.is_none());
        assert!(spec.api.swagger);
    }

    #[test]
    fn test_spec_with_explicit_api_block() {
        let yaml = r#"
version: v1
deployment: test
services:
  hello:
    image:
      name: hello-world:latest
api:
  enabled: false
  bind: "127.0.0.1:9090"
  jwt_secret: "my-secret"
  swagger: false
"#;
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert!(!spec.api.enabled);
        assert_eq!(spec.api.bind, "127.0.0.1:9090");
        assert_eq!(spec.api.jwt_secret, Some("my-secret".to_string()));
        assert!(!spec.api.swagger);
    }

    #[test]
    fn test_spec_with_partial_api_block() {
        let yaml = r#"
version: v1
deployment: test
services:
  hello:
    image:
      name: hello-world:latest
api:
  bind: "0.0.0.0:3000"
"#;
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).unwrap();
        assert!(spec.api.enabled); // default true
        assert_eq!(spec.api.bind, "0.0.0.0:3000");
        assert!(spec.api.jwt_secret.is_none()); // default None
        assert!(spec.api.swagger); // default true
    }

    // ==========================================================================
    // NetworkPolicySpec tests
    // ==========================================================================

    #[test]
    fn test_network_policy_spec_roundtrip() {
        let spec = NetworkPolicySpec {
            name: "corp-vpn".to_string(),
            description: Some("Corporate VPN network".to_string()),
            cidrs: vec!["10.200.0.0/16".to_string()],
            members: vec![
                NetworkMember {
                    name: "alice".to_string(),
                    kind: MemberKind::User,
                },
                NetworkMember {
                    name: "ops-team".to_string(),
                    kind: MemberKind::Group,
                },
                NetworkMember {
                    name: "node-01".to_string(),
                    kind: MemberKind::Node,
                },
            ],
            access_rules: vec![
                AccessRule {
                    service: "api-gateway".to_string(),
                    deployment: "*".to_string(),
                    ports: Some(vec![443, 8080]),
                    action: AccessAction::Allow,
                },
                AccessRule {
                    service: "*".to_string(),
                    deployment: "staging".to_string(),
                    ports: None,
                    action: AccessAction::Deny,
                },
            ],
        };

        let yaml = serde_yaml::to_string(&spec).unwrap();
        let deserialized: NetworkPolicySpec = serde_yaml::from_str(&yaml).unwrap();
        assert_eq!(spec, deserialized);
    }

    #[test]
    fn test_network_policy_spec_defaults() {
        let yaml = r"
name: minimal
";
        let spec: NetworkPolicySpec = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(spec.name, "minimal");
        assert!(spec.description.is_none());
        assert!(spec.cidrs.is_empty());
        assert!(spec.members.is_empty());
        assert!(spec.access_rules.is_empty());
    }

    #[test]
    fn test_access_rule_defaults() {
        let yaml = "{}";
        let rule: AccessRule = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(rule.service, "*");
        assert_eq!(rule.deployment, "*");
        assert!(rule.ports.is_none());
        assert_eq!(rule.action, AccessAction::Allow);
    }

    #[test]
    fn test_member_kind_defaults_to_user() {
        let yaml = r"
name: bob
";
        let member: NetworkMember = serde_yaml::from_str(yaml).unwrap();
        assert_eq!(member.name, "bob");
        assert_eq!(member.kind, MemberKind::User);
    }

    #[test]
    fn test_member_kind_variants() {
        for (input, expected) in [
            ("user", MemberKind::User),
            ("group", MemberKind::Group),
            ("node", MemberKind::Node),
            ("cidr", MemberKind::Cidr),
        ] {
            let yaml = format!("name: test\nkind: {input}");
            let member: NetworkMember = serde_yaml::from_str(&yaml).unwrap();
            assert_eq!(member.kind, expected);
        }
    }

    #[test]
    fn test_access_action_variants() {
        // Test via a wrapper struct since bare enums need a YAML tag
        #[derive(Debug, Deserialize)]
        struct Wrapper {
            action: AccessAction,
        }

        let allow: Wrapper = serde_yaml::from_str("action: allow").unwrap();
        let deny: Wrapper = serde_yaml::from_str("action: deny").unwrap();

        assert_eq!(allow.action, AccessAction::Allow);
        assert_eq!(deny.action, AccessAction::Deny);
    }

    #[test]
    fn test_network_policy_spec_default_impl() {
        let spec = NetworkPolicySpec::default();
        assert_eq!(spec.name, "");
        assert!(spec.description.is_none());
        assert!(spec.cidrs.is_empty());
        assert!(spec.members.is_empty());
        assert!(spec.access_rules.is_empty());
    }

    #[test]
    fn container_restart_policy_serde_roundtrip_all_kinds() {
        // Exercise every `ContainerRestartKind` variant via a JSON roundtrip.
        // Covers the `snake_case` rename (`unless_stopped`, `on_failure`) and
        // the optional `max_attempts` / `delay` fields. Validates the wire
        // format the API will expose under `/v1/containers`.
        let cases = [
            (
                ContainerRestartPolicy {
                    kind: ContainerRestartKind::No,
                    max_attempts: None,
                    delay: None,
                },
                r#"{"kind":"no"}"#,
            ),
            (
                ContainerRestartPolicy {
                    kind: ContainerRestartKind::Always,
                    max_attempts: None,
                    delay: Some("500ms".to_string()),
                },
                r#"{"kind":"always","delay":"500ms"}"#,
            ),
            (
                ContainerRestartPolicy {
                    kind: ContainerRestartKind::UnlessStopped,
                    max_attempts: None,
                    delay: None,
                },
                r#"{"kind":"unless_stopped"}"#,
            ),
            (
                ContainerRestartPolicy {
                    kind: ContainerRestartKind::OnFailure,
                    max_attempts: Some(5),
                    delay: None,
                },
                r#"{"kind":"on_failure","max_attempts":5}"#,
            ),
        ];

        for (value, expected_json) in &cases {
            let serialized = serde_json::to_string(value).expect("serialize");
            assert_eq!(&serialized, expected_json, "serialize mismatch");
            let round: ContainerRestartPolicy =
                serde_json::from_str(&serialized).expect("deserialize");
            assert_eq!(&round, value, "roundtrip mismatch");
        }
    }

    // -- §3.10: RegistryAuth ------------------------------------------------

    #[test]
    fn registry_auth_type_serializes_snake_case() {
        assert_eq!(
            serde_json::to_string(&RegistryAuthType::Basic).unwrap(),
            "\"basic\""
        );
        assert_eq!(
            serde_json::to_string(&RegistryAuthType::Token).unwrap(),
            "\"token\""
        );
    }

    #[test]
    fn registry_auth_default_auth_type_is_basic() {
        // When `auth_type` is omitted on the wire, the serde default kicks in.
        let json = r#"{"username":"u","password":"p"}"#;
        let parsed: RegistryAuth = serde_json::from_str(json).expect("parse");
        assert_eq!(parsed.auth_type, RegistryAuthType::Basic);
        assert_eq!(parsed.username, "u");
        assert_eq!(parsed.password, "p");
    }

    #[test]
    fn registry_auth_serde_roundtrip_both_variants() {
        for variant in [RegistryAuthType::Basic, RegistryAuthType::Token] {
            let cred = RegistryAuth {
                username: "ci-bot".to_string(),
                password: "s3cret".to_string(),
                auth_type: variant,
            };
            let serialized = serde_json::to_string(&cred).expect("serialize");
            let back: RegistryAuth = serde_json::from_str(&serialized).expect("deserialize");
            assert_eq!(back, cred, "roundtrip mismatch for {variant:?}");
        }
    }

    #[test]
    fn registry_auth_explicit_token_type_parses() {
        let json = r#"{"username":"oauth2accesstoken","password":"ghp_abc","auth_type":"token"}"#;
        let parsed: RegistryAuth = serde_json::from_str(json).expect("parse");
        assert_eq!(parsed.auth_type, RegistryAuthType::Token);
    }

    #[test]
    fn target_platform_as_oci_str() {
        assert_eq!(
            TargetPlatform::new(OsKind::Linux, ArchKind::Amd64).as_oci_str(),
            "linux/amd64"
        );
        assert_eq!(
            TargetPlatform::new(OsKind::Windows, ArchKind::Arm64).as_oci_str(),
            "windows/arm64"
        );
        assert_eq!(
            TargetPlatform::new(OsKind::Macos, ArchKind::Arm64).as_oci_str(),
            "darwin/arm64"
        );
    }

    #[test]
    fn os_kind_from_rust_consts() {
        assert_eq!(OsKind::from_rust_os("linux"), Some(OsKind::Linux));
        assert_eq!(OsKind::from_rust_os("windows"), Some(OsKind::Windows));
        assert_eq!(OsKind::from_rust_os("macos"), Some(OsKind::Macos));
        assert_eq!(OsKind::from_rust_os("freebsd"), None);
    }

    #[test]
    fn arch_kind_from_rust_consts() {
        assert_eq!(ArchKind::from_rust_arch("x86_64"), Some(ArchKind::Amd64));
        assert_eq!(ArchKind::from_rust_arch("aarch64"), Some(ArchKind::Arm64));
        assert_eq!(ArchKind::from_rust_arch("riscv64"), None);
    }

    #[test]
    fn service_spec_platform_yaml_round_trip_none() {
        // Omitting `platform` from YAML should deserialize as None without error,
        // even though ServiceSpec has `#[serde(deny_unknown_fields)]`.
        let yaml = r"
version: v1
deployment: test
services:
  app:
    rtype: service
    image:
      name: nginx:latest
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).expect("yaml parse");
        assert!(spec.services["app"].platform.is_none());
    }

    #[test]
    fn service_spec_platform_yaml_round_trip_some() {
        let yaml = r"
version: v1
deployment: test
services:
  app:
    rtype: service
    image:
      name: nginx:latest
    platform:
      os: windows
      arch: amd64
";
        let spec: DeploymentSpec = serde_yaml::from_str(yaml).expect("yaml parse");
        assert_eq!(
            spec.services["app"].platform,
            Some(TargetPlatform::new(OsKind::Windows, ArchKind::Amd64))
        );
    }

    #[test]
    fn service_spec_platform_serializes_omitted_when_none() {
        // Build a minimal ServiceSpec via YAML to avoid enumerating every field
        // (ServiceSpec has no Default impl and no named-struct helper).
        let yaml = r"
version: v1
deployment: test
services:
  app:
    rtype: service
    image:
      name: nginx:latest
";
        let mut spec: DeploymentSpec = serde_yaml::from_str(yaml).expect("yaml parse");
        let service = spec.services.get_mut("app").expect("service present");
        service.platform = None;
        let rendered = serde_yaml::to_string(service).expect("render");
        assert!(
            !rendered.contains("platform"),
            "platform must be omitted when None: {rendered}"
        );
    }

    #[test]
    fn target_platform_os_version_builder() {
        let p =
            TargetPlatform::new(OsKind::Windows, ArchKind::Amd64).with_os_version("10.0.26100.1");
        assert_eq!(p.os_version.as_deref(), Some("10.0.26100.1"));
        assert_eq!(p.os, OsKind::Windows);
        assert_eq!(p.arch, ArchKind::Amd64);
    }

    #[test]
    fn target_platform_os_version_yaml_roundtrip() {
        let yaml = "os: windows\narch: amd64\nosVersion: 10.0.26100.1\n";
        let p: TargetPlatform = serde_yaml::from_str(yaml).expect("yaml parse");
        assert_eq!(p.os_version.as_deref(), Some("10.0.26100.1"));
        assert_eq!(p.os, OsKind::Windows);
        assert_eq!(p.arch, ArchKind::Amd64);
    }

    #[test]
    fn target_platform_os_version_yaml_omits_when_none() {
        let p = TargetPlatform::new(OsKind::Linux, ArchKind::Amd64);
        let rendered = serde_yaml::to_string(&p).expect("render");
        assert!(
            !rendered.contains("osVersion"),
            "osVersion must be omitted when None: {rendered}"
        );
    }

    #[test]
    fn target_platform_as_detailed_str_includes_version() {
        let without = TargetPlatform::new(OsKind::Windows, ArchKind::Amd64).as_detailed_str();
        assert_eq!(without, "windows/amd64");

        let with = TargetPlatform::new(OsKind::Windows, ArchKind::Amd64)
            .with_os_version("10.0.26100.1")
            .as_detailed_str();
        assert_eq!(with, "windows/amd64 (os.version=10.0.26100.1)");
    }

    #[test]
    fn target_platform_display_ignores_version() {
        // Display deliberately stays terse so existing log lines don't change.
        let p =
            TargetPlatform::new(OsKind::Windows, ArchKind::Amd64).with_os_version("10.0.26100.1");
        assert_eq!(format!("{p}"), "windows/amd64");
    }
}