zlayer_types/

overlay.rs

//! Overlay-network configuration types shared across `ZLayer` crates.
//!
//! [`OverlayMode`] is a per-service data-plane attachment knob. It bundles two
//! independent decisions — the container-attachment topology (per-service Linux
//! bridge vs. one shared node-wide bridge + userspace free-port L4 proxy) and
//! the `WireGuard` transport (the single cluster-wide interface vs. a per-service
//! interface with isolated crypto) — into a single setting.
//!
//! Truth table:
//!
//! | mode      | shared node bridge + free-port proxy? | per-service `WireGuard` transport? | resulting behavior |
//! |-----------|----------------------------------------|------------------------------------|--------------------|
//! | `Auto`      | no  | no  | today's default: veth-per-container on a per-service Linux bridge, carried on the single cluster-wide `WireGuard` interface |
//! | `Dedicated` | no  | yes | veth-per-container on a per-service bridge, with its OWN per-service `WireGuard` transport (isolated crypto) = max isolation |
//! | `Shared`    | yes | no  | NO per-service bridge / NO per-service WG: one shared node-wide bridge for all services + a userspace free-port L4 proxy (`host:FREEPORT` -> `container_ip:port`), carried on the cluster-wide `WireGuard` interface = max sharing |
//! | `Isolated`  | no  | no  | per-service bridge on the cluster-wide `WireGuard` interface (Auto topology), but L3-fenced to its own isolation network (members reach only their own network + node IP + egress) |
//!
//! The real decision surface is the three predicate methods
//! [`OverlayMode::uses_shared_bridge`], [`OverlayMode::uses_per_service_wg`],
//! and [`OverlayMode::uses_isolation_scope`]; consult those rather than matching
//! on variants ad hoc.

use serde::{Deserialize, Serialize};

/// Per-service overlay data-plane attachment knob.
///
/// See the module docs for the full truth table; each variant bundles a
/// container-attachment topology with a `WireGuard` transport choice.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, utoipa::ToSchema)]
#[serde(rename_all = "lowercase")]
pub enum OverlayMode {
    /// Today's default behavior: veth-per-container on a per-service Linux
    /// bridge, carried on the single cluster-wide `WireGuard` interface. No
    /// shared node-wide bridge / free-port proxy and no per-service `WireGuard`
    /// transport.
    #[default]
    Auto,
    /// Max sharing: one shared node-wide bridge for all services plus a
    /// userspace free-port L4 proxy (`host:FREEPORT` -> `container_ip:port`).
    /// No per-service bridge and no per-service `WireGuard`; traffic rides the
    /// cluster-wide `WireGuard` interface.
    Shared,
    /// Max isolation: veth-per-container on a per-service bridge, with its OWN
    /// per-service `WireGuard` transport (isolated crypto context). No shared
    /// node-wide bridge / free-port proxy.
    Dedicated,
    /// Per-service bridge on the cluster-wide `WireGuard` interface (same
    /// topology + transport as [`OverlayMode::Auto`]), but L3-fenced to its own
    /// isolation network: members reach their own network's members plus the
    /// node IP and egress, never other networks' members or arbitrary cluster
    /// overlay IPs. Sugar for "Auto topology auto-fenced to an isolation network
    /// named after the service" — it reuses the same `isolation_network`
    /// membership machinery the named-isolated-networks feature already uses on
    /// every platform. Distinct from [`OverlayMode::Dedicated`], which isolates
    /// the crypto *transport* (its own `WireGuard` device), not the L3 scope.
    Isolated,
}

impl OverlayMode {
    /// Identity resolution: each variant resolves to itself. Retained so
    /// existing `.resolve()` callers keep compiling. `Auto` no longer maps to
    /// `Shared` — `Auto` now denotes today's default behavior (per-service
    /// bridge on the cluster-wide `WireGuard` interface) in its own right.
    #[must_use]
    pub fn resolve(self) -> OverlayMode {
        self
    }

    /// Whether this mode uses the shared node-wide bridge plus the userspace
    /// free-port L4 proxy. True only for [`OverlayMode::Shared`].
    #[must_use]
    pub fn uses_shared_bridge(self) -> bool {
        matches!(self, OverlayMode::Shared)
    }

    /// Whether this mode provisions its own per-service `WireGuard` transport
    /// with an isolated crypto context. True only for
    /// [`OverlayMode::Dedicated`].
    #[must_use]
    pub fn uses_per_service_wg(self) -> bool {
        matches!(self, OverlayMode::Dedicated)
    }

    /// Whether this mode is L3-fenced to its own isolation network. True only
    /// for [`OverlayMode::Isolated`]. The fence reuses the platform-neutral
    /// `isolation_network` membership channel; the network is named after the
    /// service.
    #[must_use]
    pub fn uses_isolation_scope(self) -> bool {
        matches!(self, OverlayMode::Isolated)
    }
}

/// Reserved container label naming the isolation network a container must join.
/// Read by every runtime's overlay attach path (via
/// [`crate::overlay::OverlayMode`] + the agent's `resolve_isolation_network`)
/// and by the Windows HCS create path. An explicit value always wins over
/// mode-derived isolation scoping. Canonical definition; per-crate copies in
/// the api/agent crates carry the same string.
pub const ISOLATION_NETWORK_LABEL: &str = "com.zlayer.isolation_network";

/// Per-service overlay configuration, populated from the service spec.
///
/// `parent` names another overlay this one should nest under. In v0.51 only
/// `None` / `Some("cluster")` is honored; any other value triggers a warn-
/// and-fallback (treated as `None`). Future rounds may allow service-of-
/// service nesting.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct OverlayConfig {
    #[serde(default)]
    pub mode: OverlayMode,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub parent: Option<String>,
}

impl OverlayConfig {
    /// Returns the resolved parent name for v0.51: `None` if the parent is
    /// `None` or `Some("cluster")`; logs a warning and falls back to `None`
    /// for any other value.
    #[must_use]
    pub fn resolved_parent_v0_51(&self) -> Option<&str> {
        match self.parent.as_deref() {
            None | Some("cluster") => None,
            Some(other) => {
                tracing::warn!(
                    parent = other,
                    "OverlayConfig.parent only supports `cluster` (or unset) in v0.51; \
                     service-of-service nesting is reserved for a future round. \
                     Falling back to cluster parent.",
                );
                None
            }
        }
    }
}

/// Egress policy for a workload's outbound connectivity.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EgressPolicy {
    /// No outbound network at all.
    None,
    /// Full outbound (DNS/HTTP/HTTPS + arbitrary) — normal containers.
    Full,
}

/// Resolved network-isolation policy for a workload, derived from its
/// `OverlayMode` + `NetworkMode` + optional explicit isolation-network label.
/// Each runtime translates this into its own enforcement (Seatbelt `.sb` ACL,
/// Linux iptables ISO chain, HCN network, …).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NetworkIsolation {
    /// Isolation network name. `None` = flat cluster mesh (reach any overlay peer).
    /// `Some(_)` = fenced to this named network's members only.
    pub scope: Option<String>,
    /// When true, the workload must NOT be granted broad cluster-overlay reach
    /// (isolated/dedicated). When false, it may reach the whole overlay (normal).
    pub fenced: bool,
    /// Whether the workload may reach the daemon/node overlay IP.
    pub allow_host: bool,
    /// Outbound policy.
    pub egress: EgressPolicy,
}

/// Resolve the effective [`NetworkIsolation`] for a workload.
///
/// Precedence: `NetworkMode` hard cases first (None → no net; Host → full host
/// opt-in), otherwise derive from `OverlayMode`. `auto`/`shared` = Docker-normal
/// (unfenced, reachable). `isolated`/`dedicated` = fenced to their own network
/// (explicit label wins, else the service name). `explicit_isolation_label`
/// comes from the `ISOLATION_NETWORK_LABEL` container label, if present.
#[must_use]
pub fn resolve_network_isolation(
    mode: OverlayMode,
    network_mode_is_none: bool,
    network_mode_is_host: bool,
    service: &str,
    explicit_isolation_label: Option<&str>,
) -> NetworkIsolation {
    if network_mode_is_none {
        return NetworkIsolation {
            scope: None,
            fenced: true,
            allow_host: false,
            egress: EgressPolicy::None,
        };
    }
    if network_mode_is_host {
        return NetworkIsolation {
            scope: None,
            fenced: false,
            allow_host: true,
            egress: EgressPolicy::Full,
        };
    }
    let fenced = mode.uses_isolation_scope() || mode.uses_per_service_wg();
    let scope = if fenced {
        Some(explicit_isolation_label.map_or_else(|| service.to_string(), str::to_string))
    } else {
        explicit_isolation_label.map(str::to_string)
    };
    NetworkIsolation {
        scope,
        fenced,
        allow_host: true,
        egress: EgressPolicy::Full,
    }
}

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

    #[test]
    fn overlay_mode_default_is_auto() {
        assert_eq!(OverlayMode::default(), OverlayMode::Auto);
    }

    #[test]
    fn isolation_network_label_is_canonical() {
        assert_eq!(ISOLATION_NETWORK_LABEL, "com.zlayer.isolation_network");
    }

    #[test]
    fn overlay_mode_resolve() {
        assert_eq!(OverlayMode::Auto.resolve(), OverlayMode::Auto);
        assert_eq!(OverlayMode::Shared.resolve(), OverlayMode::Shared);
        assert_eq!(OverlayMode::Dedicated.resolve(), OverlayMode::Dedicated);
        assert_eq!(OverlayMode::Isolated.resolve(), OverlayMode::Isolated);
    }

    #[test]
    fn overlay_mode_predicates() {
        assert_eq!(
            (
                OverlayMode::Auto.uses_shared_bridge(),
                OverlayMode::Auto.uses_per_service_wg()
            ),
            (false, false)
        );
        assert_eq!(
            (
                OverlayMode::Dedicated.uses_shared_bridge(),
                OverlayMode::Dedicated.uses_per_service_wg()
            ),
            (false, true)
        );
        assert_eq!(
            (
                OverlayMode::Shared.uses_shared_bridge(),
                OverlayMode::Shared.uses_per_service_wg()
            ),
            (true, false)
        );
    }

    #[test]
    fn overlay_mode_isolated_predicates() {
        assert!(OverlayMode::Isolated.uses_isolation_scope());
        assert!(!OverlayMode::Isolated.uses_shared_bridge());
        assert!(!OverlayMode::Isolated.uses_per_service_wg());
        assert!(!OverlayMode::Auto.uses_isolation_scope());
        assert!(!OverlayMode::Shared.uses_isolation_scope());
        assert!(!OverlayMode::Dedicated.uses_isolation_scope());
    }

    #[test]
    fn overlay_mode_serde_lowercase() {
        assert_eq!(
            serde_json::to_string(&OverlayMode::Auto).unwrap(),
            "\"auto\""
        );
        assert_eq!(
            serde_json::to_string(&OverlayMode::Shared).unwrap(),
            "\"shared\""
        );
        assert_eq!(
            serde_json::to_string(&OverlayMode::Dedicated).unwrap(),
            "\"dedicated\""
        );
        assert_eq!(
            serde_json::to_string(&OverlayMode::Isolated).unwrap(),
            "\"isolated\""
        );
        assert_eq!(
            serde_json::from_str::<OverlayMode>("\"shared\"").unwrap(),
            OverlayMode::Shared,
        );
        assert_eq!(
            serde_json::from_str::<OverlayMode>("\"isolated\"").unwrap(),
            OverlayMode::Isolated,
        );
    }

    #[test]
    fn overlay_config_default_is_auto_no_parent() {
        let cfg = OverlayConfig::default();
        assert_eq!(cfg.mode, OverlayMode::Auto);
        assert_eq!(cfg.parent, None);
        assert_eq!(cfg.resolved_parent_v0_51(), None);
    }

    #[test]
    fn overlay_config_cluster_parent_is_none() {
        let cfg = OverlayConfig {
            mode: OverlayMode::Shared,
            parent: Some("cluster".to_string()),
        };
        assert_eq!(cfg.resolved_parent_v0_51(), None);
    }

    #[test]
    fn overlay_config_other_parent_warns_and_returns_none() {
        let cfg = OverlayConfig {
            mode: OverlayMode::Shared,
            parent: Some("svc-other".to_string()),
        };
        assert_eq!(cfg.resolved_parent_v0_51(), None);
    }

    #[test]
    fn resolve_isolation_auto_is_unfenced_full_and_host() {
        let iso = resolve_network_isolation(OverlayMode::Auto, false, false, "svc", None);
        assert_eq!(
            iso,
            NetworkIsolation {
                scope: None,
                fenced: false,
                allow_host: true,
                egress: EgressPolicy::Full,
            }
        );
    }

    #[test]
    fn resolve_isolation_shared_is_unfenced() {
        let iso = resolve_network_isolation(OverlayMode::Shared, false, false, "svc", None);
        assert!(!iso.fenced);
        assert_eq!(iso.scope, None);
        assert_eq!(iso.egress, EgressPolicy::Full);
        assert!(iso.allow_host);
    }

    #[test]
    fn resolve_isolation_isolated_is_fenced_to_service() {
        let iso = resolve_network_isolation(OverlayMode::Isolated, false, false, "svc", None);
        assert!(iso.fenced);
        assert_eq!(iso.scope.as_deref(), Some("svc"));
        assert!(iso.allow_host);
        assert_eq!(iso.egress, EgressPolicy::Full);
    }

    #[test]
    fn resolve_isolation_isolated_explicit_label_overrides_service() {
        let iso =
            resolve_network_isolation(OverlayMode::Isolated, false, false, "svc", Some("netA"));
        assert!(iso.fenced);
        assert_eq!(iso.scope.as_deref(), Some("netA"));
    }

    #[test]
    fn resolve_isolation_dedicated_is_fenced() {
        let iso = resolve_network_isolation(OverlayMode::Dedicated, false, false, "svc", None);
        assert!(iso.fenced);
        assert_eq!(iso.scope.as_deref(), Some("svc"));
        assert_eq!(iso.egress, EgressPolicy::Full);
    }

    #[test]
    fn resolve_isolation_unfenced_label_still_sets_scope() {
        // An explicit label on an unfenced (auto) workload still names a scope,
        // but the workload is not fenced.
        let iso = resolve_network_isolation(OverlayMode::Auto, false, false, "svc", Some("netA"));
        assert!(!iso.fenced);
        assert_eq!(iso.scope.as_deref(), Some("netA"));
    }

    #[test]
    fn resolve_isolation_network_none_has_no_net() {
        let iso = resolve_network_isolation(OverlayMode::Auto, true, false, "svc", Some("netA"));
        assert_eq!(
            iso,
            NetworkIsolation {
                scope: None,
                fenced: true,
                allow_host: false,
                egress: EgressPolicy::None,
            }
        );
    }

    #[test]
    fn resolve_isolation_network_host_is_unfenced_full() {
        // Host mode wins over an isolated overlay mode: full host opt-in.
        let iso =
            resolve_network_isolation(OverlayMode::Isolated, false, true, "svc", Some("netA"));
        assert_eq!(
            iso,
            NetworkIsolation {
                scope: None,
                fenced: false,
                allow_host: true,
                egress: EgressPolicy::Full,
            }
        );
    }
}