Struct OverlayManager 

pub struct OverlayManager { /* private fields */ }

Manages overlay networks for a deployment

Implementations

impl OverlayManager

pub async fn new(deployment: String) -> Result<Self, AgentError>

Create a new overlay manager for a deployment (legacy single-node path).

This constructor hands out container IPs from the full default cluster /16 (10.200.0.0/16). In multi-node deployments every node’s agent would then independently allocate from the same flat range, producing IP collisions. Prefer OverlayManager::with_slice for cluster deployments so the agent is bounded to a per-node slice assigned by the leader’s NodeSliceAllocator.

Errors

Returns an error if the overlay manager cannot be initialized.

Panics

Panics if the default CIDR 10.200.0.0/16 cannot be parsed (this is a compile-time constant).

pub fn with_slice( deployment: String, cluster_cidr: IpNetwork, slice_cidr: IpNetwork, port: u16, ) -> Self

Create an OverlayManager bound to a per-node slice.

slice_cidr is a /28 (or whatever the cluster’s slice prefix is) owned by this node, assigned by the leader’s NodeSliceAllocator. The internal IpAllocator is bounded to this slice so container IPs never collide across nodes.

cluster_cidr is the full cluster CIDR (e.g. 10.200.0.0/16), kept for configuration / logging purposes. The allocator itself only uses slice_cidr.

pub fn with_overlay_port(self, port: u16) -> Self

Set the WireGuard listen port for the overlay network.

pub fn with_nat_config(self, nat: NatConfig) -> Self

Set the NAT traversal configuration for the overlay network.

When set, the NatConfig is threaded into every OverlayConfig the manager builds (global and per-service). When unset (the default), OverlayConfig::default() is used, which itself defaults to NatConfig::default() — i.e. NAT traversal enabled with public STUN.

pub async fn service_count(&self) -> usize

Returns the number of services currently registered with this manager.

Counts entries in service_interfaces, which is populated by OverlayManager::setup_service_overlay regardless of whether the underlying overlay transport was successfully created or fell through to direct networking. Useful for the race regression test in tests/overlay_setup_race.rs and for telemetry endpoints.

pub fn nat_enabled(&self) -> bool

Returns whether NAT traversal is enabled for this manager.

Reflects the most recent with_nat_config() call. When no NAT config has been provided this falls back to NatConfig::default which has enabled = true.

pub fn nat_config(&self) -> Option<NatConfig>

Returns a clone of the configured NatConfig, or None if no override was provided. Used by the API layer to surface the daemon’s effective NAT configuration without exposing the raw NatConfig::default() baseline.

pub async fn start_nat_traversal(&self) -> Result<bool, AgentError>

Bootstrap a NatTraversal orchestrator for this manager.

Constructs a fresh NatTraversal from the configured NatConfig (defaulting when none is set), gathers ICE-style local candidates (host + STUN reflexive + relay) and stores it for later OverlayManager::nat_maintenance_tick / status calls.

No-op when enabled = false in the configured NatConfig. Failures during candidate gathering are logged and surfaced as Ok(false) so the caller can decide whether to spawn a maintenance loop or skip it.

Returns Ok(true) when the traversal was successfully constructed and at least one candidate was gathered, Ok(false) when NAT is disabled or candidate gathering yielded nothing actionable.

Errors

Returns an error only on unexpected internal failures; STUN/TURN network errors are downgraded to Ok(false) with a warning log so the daemon can boot with NAT degraded rather than aborting.

pub async fn nat_maintenance_tick(&self) -> Result<(), AgentError>

Periodic NAT traversal maintenance: re-probe STUN, refresh relays, attempt to upgrade relayed peer connections to direct/hole-punched.

Intended to be called from a tokio::time::interval loop spawned by the daemon. No-op when OverlayManager::start_nat_traversal has not yet succeeded.

Errors

Returns an error when the underlying STUN refresh fails. The daemon’s loop logs and ignores these so a transient STUN outage doesn’t kill the maintenance task.

pub async fn nat_status_snapshot(&self) -> NatStatusSnapshot

Snapshot the current NAT traversal state for API consumers.

Returns an empty snapshot when NAT traversal has not been started. Per-peer entries are not yet tracked here (the agent path does not route peers through NatTraversal::connect_to_peer); callers should treat the peers list as advisory.

pub fn set_dns_config( &mut self, addr: Option<SocketAddr>, domain: Option<String>, )

Record the overlay DNS server address and zone domain so attaches can propagate them to HCN endpoint schemas (Windows) and future per-container DNS plumbing (Linux /etc/resolv.conf).

addr is the socket address the overlay hickory DNS server is listening on (typically overlay_ip:15353). domain is the DNS zone (e.g. "overlay.local"). Either may be omitted independently.

pub fn with_dns_config( self, addr: Option<SocketAddr>, domain: Option<String>, ) -> Self

Builder-style variant of OverlayManager::set_dns_config.

pub fn dns_server_addr(&self) -> Option<SocketAddr>

Returns the overlay DNS server address if the daemon bootstrapped one.

pub fn dns_domain(&self) -> Option<&str>

Returns the overlay DNS zone domain, if configured.

pub async fn setup_global_overlay(&mut self) -> Result<(), AgentError>

Setup the global overlay network for the deployment

Errors

Returns an error if key generation or interface creation fails.

pub async fn setup_service_overlay( &self, service_name: &str, ) -> Result<String, AgentError>

Setup a service-scoped overlay network

Errors

Returns an error if the overlay interface cannot be created.

pub async fn attach_container( &self, container_pid: u32, service_name: &str, join_global: bool, ) -> Result<IpAddr, AgentError>

Add a container to the appropriate overlay networks.

On non-Linux platforms this is a no-op: per-container overlay attachment relies on Linux network namespaces (veth pairs + nsenter). On macOS, containers share the host network, so the node’s overlay IP is returned directly and the proxy differentiates traffic by port.

Errors

Returns an error if the container cannot be attached to the overlay network.

pub async fn teardown_service_overlay(&self, service_name: &str)

Tear down the overlay network for a single service.

Removes the service’s TUN transport (destroying the interface) and clears its entry from the interface tracking map. This is safe to call even if no overlay was created for the service (it will be a no-op).

pub async fn cleanup(&mut self) -> Result<(), AgentError>

Cleanup all overlay networks

Errors

Returns an error if cleanup operations fail.

pub fn node_ip(&self) -> Option<IpAddr>

Returns this node’s IP on the global overlay network, if available.

This is set after [setup_global_overlay] completes successfully.

pub fn deployment(&self) -> &str

Returns the deployment name this overlay manager was created for.

pub fn global_interface(&self) -> Option<&str>

Returns the global overlay interface name, if one has been created.

pub fn overlay_port(&self) -> u16

Returns the WireGuard listen port for the overlay network.

pub fn has_global_transport(&self) -> bool

Returns true if the global overlay transport is active.

pub async fn service_transport_count(&self) -> usize

Returns the number of service-specific overlay transports currently active.

pub fn overlay_cidr(&self) -> String

Returns the CIDR string for the overlay IP allocator.

pub fn slice_cidr(&self) -> Option<IpNetwork>

Returns the per-node slice CIDR this manager was built with, or None if the legacy OverlayManager::new constructor was used.

pub fn cluster_cidr(&self) -> Option<IpNetwork>

Returns the full cluster CIDR, if this manager was constructed with one. The legacy OverlayManager::new path stores the default 10.200.0.0/16.

pub async fn persist_ipam_state(&self, path: &Path) -> Result<(), AgentError>

Persist the IPAM allocator state to path.

The state is a small JSON blob capturing the allocator’s CIDR bound and its next-offset counter so restarts don’t re-hand-out the same IPs.

Errors

Returns an error if the file cannot be written.

pub async fn restore_ipam_state( &mut self, path: &Path, ) -> Result<(), AgentError>

Restore IPAM allocator state from path.

If the file does not exist this is a no-op (the allocator keeps its current counter). On load mismatch (e.g. the persisted CIDR differs from the allocator’s current CIDR) the counter is left untouched and a warning is emitted.

Errors

Returns an error if the file exists but cannot be read or parsed.

pub fn ip_alloc_stats(&self) -> (u64, IpAddr)

Returns IP allocation statistics: (allocated_count, next_offset).