Struct OverlayManager 

pub struct OverlayManager { /* private fields */ }

Manages overlay networks for a deployment by delegating all mechanics to the zlayer-overlayd daemon.

This struct holds only cluster-brain / cached state; the actual overlay machinery lives in overlayd and is reached through OverlayManager::client.

Implementations

impl OverlayManager

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

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

Uses the default cluster /16. Prefer OverlayManager::with_slice for cluster deployments. The overlayd IPC client is connected lazily on first use (via the socket under the system-default data dir).

Errors

Infallible today; the Result is preserved for ABI parity with callers.

Panics

Panics only if the compile-time-constant default CIDR 10.200.0.0/16 fails to parse (impossible).

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

Create an OverlayManager bound to a per-node slice.

slice_cidr is the per-node slice owned by this node; cluster_cidr is the full cluster CIDR. Both are forwarded to overlayd in SetupGlobalOverlay.

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. overlayd owns the live NAT orchestrator; this records the toggle so SetupGlobalOverlay can carry nat_enabled and the daemon can decide whether to drive NatTick.

pub fn with_uapi_sock_dir(self, dir: impl Into<PathBuf>) -> Self

Override the WireGuard UAPI socket directory. Retained for API parity; overlayd owns the real transport’s socket directory.

pub fn with_data_dir(self, dir: impl Into<PathBuf>) -> Self

Override the data directory used to resolve the overlayd IPC socket.

pub fn with_local_node_id(self, node_id: u64) -> Self

Set the local raft node id (builder-style).

pub fn set_local_node_id(&mut self, node_id: u64)

Post-construction setter for the local raft node id. Forwards SetLocalNodeId to overlayd best-effort.

pub async fn set_local_wg_pubkey(&self, pubkey: String)

Record this node’s cluster WireGuard public key (base64) and forward it to overlayd so service subnets can be added to the cluster transport’s local AllowedIPs.

pub async fn service_count(&self) -> usize

Returns the number of services currently registered (cached Status).

pub fn nat_enabled(&self) -> bool

Returns whether NAT traversal is enabled for this manager.

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

Returns a clone of the configured NatConfig, or None.

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

Bootstrap NAT traversal. overlayd starts NAT lazily on its first NatTick, so this is a thin shim that reports whether NAT is enabled.

Errors

Infallible today; preserved for ABI parity.

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

Run one NAT-traversal maintenance tick by forwarding NatTick to overlayd.

Errors

Returns an error when overlayd reports a NAT refresh failure.

pub async fn nat_status_snapshot(&self) -> NatStatusSnapshot

Snapshot the current NAT traversal state for API consumers.

overlayd owns the live NAT orchestrator and does not surface per-peer candidate detail over the IPC contract, so this returns an empty snapshot. Kept for API parity.

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

Record the overlay DNS server address and zone domain (cached locally; forwarded to overlayd on each container attach).

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 configured.

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 by delegating to overlayd.

Forwards the local node id and wg pubkey first (so overlayd has the cluster-brain context), then issues SetupGlobalOverlay and caches the returned interface name plus the node IP / CIDRs reported by Status.

Errors

Returns an error if overlayd fails to bring up the overlay.

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

Set up the per-service overlay segment by delegating to overlayd.

Returns a [ServiceOverlayInfo] describing the segment. The container-attach handle (bridge name on Linux, interface elsewhere) is info.name. In Dedicated mode the wg_public_key/wg_port/ overlay_ip/subnet fields carry the per-service WireGuard transport’s identity so the deploy path can publish it to Raft and mesh with the other hosting nodes; in Shared mode those fields are None.

mode is the service’s resolved [OverlayMode], read from its spec at the deploy call site. In Shared mode overlayd attaches the service to the cluster transport via a per-node bridge; in Dedicated mode it stands up a per-service WireGuard transport with its own crypto context and reports its identity via OverlaydResponse::ServiceOverlay.

Errors

Returns an error if overlayd fails to create the segment.

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 by delegating to overlayd (AttachContainer with a LinuxPid handle).

Errors

Returns an error if overlayd cannot attach the container.

pub async fn attach_container_guest( &self, id: &str, service_name: &str, join_global: bool, ) -> Result<GuestOverlayConfig, AgentError>

Attach a guest-managed container (a VM with no host netns/PID) to the overlay by asking overlayd to allocate the overlay identity (keypair + address + the current peer set) and register the generated public key in the mesh. The caller ships the returned [GuestOverlayConfig] into the guest (over vsock) where it brings up its own WireGuard device.

id is the opaque container id used to scope the allocation so a later detach_container_guest can release the address + remove the peer.

Errors

Returns an error if overlayd cannot allocate/register the guest.

pub async fn detach_container_guest(&self, id: &str) -> Result<(), AgentError>

Detach a guest-managed container: release its overlay IP and remove its registered mesh peer.

Errors

Returns an error if overlayd cannot detach the container.

pub async fn detach_container(&self, pid: u32) -> Result<(), AgentError>

Release the overlay resources held by a Linux container by delegating to overlayd (DetachContainer with a LinuxPid handle).

Errors

Returns an error if overlayd reports a detach failure.

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

Tear down the per-service overlay segment for service_name.

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

Cleanup all overlay networks (tears down the global overlay in overlayd).

Errors

Returns an error if overlayd reports a teardown failure.

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

Returns this node’s IP on the global overlay network (cached).

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 (cached).

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 (cached: an interface name has been recorded).

pub async fn service_bridge_count(&self) -> usize

Returns the number of per-service overlay bridges currently active.

pub async fn add_global_peer(&self, peer: &PeerInfo) -> Result<(), AgentError>

Add a peer to the live global overlay transport by delegating to overlayd.

The parameter type is preserved (&zlayer_overlay::PeerInfo) so the one caller (zlayer-api’s internal add-peer handler) compiles unchanged; the shim converts it to a wire-safe PeerSpec.

Errors

Returns an error if overlayd rejects the peer (e.g. overlay not yet up).

pub async fn add_service_peer( &self, service: &str, peer: &PeerInfo, subnet: &str, ) -> Result<(), AgentError>

Add a peer to a service’s dedicated per-service overlay transport.

Analogous to OverlayManager::add_global_peer but scoped to service’s [OverlayMode::Dedicated] device: first the peer itself (AddPeer with scope: Service), then the service subnet plumbed into that peer’s AllowedIPs (AddAllowedIp with the same scope).

Errors

Returns an error if overlayd rejects the peer or the allowed-IP add (e.g. the service’s dedicated transport is not yet up).

pub async fn remove_service_peer( &self, service: &str, pubkey: &str, ) -> Result<(), AgentError>

Remove a peer (by base64 public key) from a service’s dedicated per-service overlay transport.

Errors

Returns an error if overlayd reports the removal failed.

pub fn overlay_cidr(&self) -> String

Returns the CIDR string for the overlay IP allocator (cached cluster CIDR).

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

Returns the per-node slice CIDR this manager was built with, or None.

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

Returns the full cluster CIDR, if known.

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

Persist the IPAM allocator state. overlayd owns IPAM; this is a no-op retained for ABI parity with callers.

Errors

Infallible today.

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

Restore IPAM allocator state. overlayd owns IPAM; this is a no-op retained for ABI parity with callers.

Errors

Infallible today.

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

Returns IP allocation statistics: (allocated_count, base_addr).

overlayd owns IPAM and does not surface allocation counters over IPC, so this reports (0, base) derived from the cached cluster CIDR.