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_relay_credential(self, credential: impl Into<String>) -> Self

Set the cluster-shared credential the built-in relay server derives its auth key from. Folded into NatConfigSpec.relay_server.auth_credential when SetupGlobalOverlay forwards the NAT config to overlayd, so every node’s relay client derives the same BLAKE2b key. An empty / whitespace credential is ignored (treated as “none supplied”).

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 with_host_adapter_mandatory(self, mandatory: bool) -> Self

Mark the node’s host overlay adapter (utun) as MANDATORY: a bringup failure becomes a hard error instead of a silent degrade. Set by the daemon for host-shared macOS runtimes where the utun is the data path.

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 by asking overlayd (which owns the live orchestrator) over the NatStatus IPC.

Converts the wire NatStatusWire into the NatStatusSnapshot/NatPeerSnapshot the API layer maps. Returns an empty snapshot when NAT is disabled or overlayd is unreachable — callers surface that as “NAT disabled / no data” rather than an error.

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, ephemeral: bool, isolation_network: Option<String>, dns_domain_override: Option<String>, ) -> 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, isolation_network: Option<String>, dns_domain_override: Option<String>, ) -> 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 write_scoped_resolver( &self, zone: &str, node_ip: IpAddr, port: Option<u16>, ) -> Result<(), AgentError>

Ask the ROOT overlayd to write a macOS /etc/resolver/<zone> scoped resolver pointing at this node’s overlay DNS (privileged path the rootless daemon cannot perform itself).

Errors

Returns an error if overlayd cannot write the resolver file.

pub async fn remove_scoped_resolver(&self, zone: &str) -> Result<(), AgentError>

Ask the ROOT overlayd to remove a macOS /etc/resolver/<zone> scoped resolver file.

Errors

Returns an error if overlayd cannot remove the resolver file.

pub async fn attach_container_host_shared( &self, container_id: &str, service_name: &str, ephemeral: bool, isolation_network: Option<String>, dns_domain_override: Option<String>, ) -> Result<IpAddr, AgentError>

Attach a macOS host-shared / VM container (Seatbelt, native-VZ, libkrun) to the overlay as a FIRST-CLASS member: overlayd allocates a distinct overlay /32 from the node slice, adds it as a utun alias so it is locally deliverable, and applies isolation membership. Returns the allocated overlay IP (the caller surfaces it for DNS + zlayer ps). NEVER the node IP. The caller then forwards <overlay_ip>:port to the container’s local delivery address.

Errors

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

pub async fn detach_container_host_shared( &self, container_id: &str, ) -> Result<(), AgentError>

Detach a macOS host-shared / VM container: release its overlay IP and remove its utun alias + isolation membership.

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 prune_orphan_bridges( &self, live_bridge_names: Vec<String>, ) -> Vec<String>

Reclaim orphaned per-service host bridges (and stale device veths) that no live deployment still owns, by delegating to overlayd. live_bridge_names is the full set of zl-…-b bridge names every currently-restored service SHOULD own (computed by the daemon from storage via OverlayManager::service_bridge_name); overlayd deletes every matching zl-…-b/-d link NOT in that set and releases its subnet/AllowedIPs.

Best-effort: a failure is logged, never propagated. Returns the names overlayd actually reclaimed (empty on failure or off Linux).

pub fn service_bridge_name(&self, service: &str) -> String

Deterministic per-service bridge name for service, identical by construction to the name overlayd creates server-side (make_interface_name(&[deployment, instance_id, service], "b")). The daemon uses this to compute the live-bridge set it hands OverlayManager::prune_orphan_bridges.

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_global_peer_with_candidates( &self, peer: &PeerInfo, candidates: Vec<NatCandidateWire>, ) -> Result<(), AgentError>

Add a global-overlay peer along with the NAT candidates it advertised at join time. overlayd records the candidates and, on its next NAT tick, hole-punches / relays toward the peer when its direct endpoint does not establish a WireGuard handshake. The candidate-free OverlayManager::add_global_peer is the back-compat thin wrapper.

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.