Struct ProxyManager 

pub struct ProxyManager { /* private fields */ }

Manages proxy routing for agent-controlled services

The ProxyManager coordinates between the agent’s service lifecycle and the proxy crate’s routing/load balancing infrastructure. It supports:

• HTTP/HTTPS/WebSocket (L7): Multiple port listeners sharing the same ServiceRegistry for request matching and load balancing.
• TCP/UDP (L4): Standalone stream proxy listeners that forward raw connections/datagrams to backends via the StreamRegistry.

Implementations

impl ProxyManager

pub fn new( config: ProxyManagerConfig, registry: Arc<ServiceRegistry>, cert_manager: Option<Arc<CertManager>>, ) -> Self

Create a new ProxyManager with the given configuration, service registry, and optional certificate manager.

pub fn registry(&self) -> Arc<ServiceRegistry>

Get a reference to the service registry

pub fn load_balancer(&self) -> Arc<LoadBalancer>

Get a reference to the load balancer

pub fn active_connections(&self) -> u64

Get the number of currently active proxy connections.

pub fn cert_manager(&self) -> Option<&Arc<CertManager>>

Get a reference to the certificate manager (if configured)

pub fn set_stream_registry(&mut self, registry: Arc<StreamRegistry>)

Set the stream registry for L4 proxy integration (TCP/UDP)

pub fn with_stream_registry(self, registry: Arc<StreamRegistry>) -> Self

Builder pattern: add stream registry for L4 proxy integration

pub fn stream_registry(&self) -> Option<&Arc<StreamRegistry>>

Get the stream registry (if configured)

pub fn set_network_policy_checker(&mut self, checker: NetworkPolicyChecker)

Set the network policy checker for access control enforcement

pub fn with_network_policy_checker(self, checker: NetworkPolicyChecker) -> Self

Builder pattern: add network policy checker for access control enforcement

pub async fn listen_on(&self, port: u16, bind_ip: IpAddr) -> Result<()>

Start listening on a specific port bound to the given address.

If already listening on this port, skip. All port listeners share the same ServiceRegistry for request matching.

Errors

Returns an error if the proxy server cannot be started.

pub async fn listen_on_tls(&self, port: u16, bind_ip: IpAddr) -> Result<()>

Start an HTTPS listener on the given port using SniCertResolver for dynamic cert selection.

If already listening on this port, skip. Requires a CertManager to be configured; logs a warning and returns Ok(()) if not.

Errors

Returns an error if the HTTPS proxy server cannot be started.

pub async fn stop(&self)

Stop all proxy servers on all ports.

After signalling each server to shut down, waits up to 30 seconds for active connections to drain before returning.

pub async fn unbind(&self, port: u16)

Remove and shut down the listener on a specific port.

pub async fn ensure_ports_for_service( &self, spec: &ServiceSpec, overlay_ip: Option<IpAddr>, ) -> Result<()>

Scan a service’s endpoints and ensure the proxy is listening on all required ports.

• HTTP/HTTPS/WebSocket endpoints start an HTTP proxy listener.
• TCP endpoints bind a TcpListener and spawn a TcpStreamService.
• UDP endpoints bind a UdpSocket and spawn a UdpStreamService.

Bind address is determined by the expose type:

• Public endpoints bind to 0.0.0.0 (all interfaces).
• Internal endpoints bind to the overlay IP so they are only reachable from within the overlay network. If no overlay is available, internal endpoints bind to 127.0.0.1 (localhost only).

Errors

Returns an error if an HTTP/HTTPS listener cannot be started.

pub async fn publish_loopback_for_container( &self, service_name: &str, spec: &ServiceSpec, container_ip: IpAddr, port_override: Option<u16>, )

Publish a single container’s exposed ports on the node loopback (127.0.0.1:<endpoint.port>), forwarding to wherever the container actually listens.

This implements the GitHub-Actions “service published to localhost” convention so a consumer sharing the node loopback can reach the service at localhost:<port>. The published port is always endpoint.port; the backend the listener forwards to is (container_ip, port_override.unwrap_or(endpoint.target_port())), which is already runtime-resolved by the caller:

• On the macOS seatbelt/libkrun runtimes every replica shares the host 127.0.0.1 and gets a unique port_override, so the container listens on 127.0.0.1:<port_override> and we forward there.
• On Linux/VZ/HCS the container listens on its overlay IP, so container_ip is the overlay address and port_override is None, forwarding to overlay_ip:<target_port>.

Backends accumulate across replicas so multiple members round-robin behind the single loopback port. Public endpoints are skipped: they are already bound on 0.0.0.0 and therefore already reachable on loopback — binding 127.0.0.1:<port> again would fail with EADDRINUSE.

This NEVER rewrites a container’s own loopback: it only binds the NODE’s 127.0.0.1 and forwards to the container’s runtime-resolved address.

Bind failures are tolerated (logged at warn!); this never panics and never returns an error.

pub async fn unpublish_loopback_for_container( &self, spec: &ServiceSpec, container_ip: IpAddr, port_override: Option<u16>, )

Remove a single container’s backend from the node-loopback publish path. Mirrors Self::publish_loopback_for_container: it recomputes the same (container_ip, port_override.unwrap_or(target_port)) backend per endpoint and drops it from the loopback registry.

When a published port’s backend set becomes empty, the registry entry is unregistered and the loopback listener is forgotten so the port is freed for the next bind. Public endpoints are skipped (they were never published here).

pub async fn add_service(&self, name: &str, spec: &ServiceSpec)

Add routes for a service based on its specification

This creates proxy routes for each endpoint defined in the ServiceSpec. HTTP/HTTPS/WebSocket endpoints get L7 routes via the ServiceRegistry. TCP/UDP endpoints are tracked but their L4 registration is handled by the ServiceManager::register_service_routes() method.

pub async fn remove_service(&self, name: &str)

Remove all routes, L4 listeners, and HTTP server handles for a service.

This performs a full cleanup of all proxy resources associated with the service:

• Removes L7 (HTTP/HTTPS/WebSocket) routes from the ServiceRegistry
• Unregisters TCP/UDP stream services from the StreamRegistry
• Removes port tracking for TCP/UDP listeners
• Shuts down HTTP proxy server handles that were exclusively owned by this service (only if no other service uses the same port)

pub async fn add_backend(&self, service: &str, addr: SocketAddr)

Add a single backend to a service.

Adds to the service-level LB group and to every per-endpoint LB group tracked for service. Per-endpoint role filtering happens at collection time in the agent’s service manager, so any backend surfaced here is already eligible for every endpoint.

pub async fn remove_backend(&self, service: &str, addr: SocketAddr)

Remove a backend from a service.

Removes from the service-level LB group and from every per-endpoint LB group.

pub async fn update_backend_health( &self, service: &str, addr: SocketAddr, healthy: bool, )

Update the health status of a backend in the load balancer.

Delegates to LoadBalancer::mark_health so that unhealthy backends are skipped during selection. Health is tracked on both the service-level group and every per-endpoint group that contains this address.

pub async fn update_backends(&self, service: &str, addrs: Vec<SocketAddr>)

Update the backends for every endpoint of a service with the same list.

Use this only when caller cannot distinguish per-endpoint backend sets (e.g., legacy paths that do not honor target_role). Prefer Self::update_endpoint_backends when per-endpoint filtering is possible.

pub async fn update_endpoint_backends( &self, service: &str, endpoint_name: &str, addrs: Vec<SocketAddr>, )

Update backends for a single L7 endpoint of a service.

This honors [EndpointSpec::target_role] filtering: the caller supplies the role-filtered backend list and this method updates only the routes and LB group corresponding to (service, endpoint_name).

pub async fn route_count(&self) -> usize

Get the number of registered routes

pub async fn list_services(&self) -> Vec<String>

Get the list of registered service names

pub async fn has_service(&self, name: &str) -> bool

Check if a service has any registered endpoints

Trait Implementations

impl Drop for ProxyManager

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.