Struct ControlHandler 

pub struct ControlHandler { /* private fields */ }

Control channel handler for a single tunnel connection

The ControlHandler manages the lifecycle of a tunnel connection, including:

• WebSocket upgrade and authentication
• Service registration and unregistration
• Heartbeat monitoring
• Message routing between server and client

Example

use std::sync::Arc;
use zlayer_tunnel::{TunnelRegistry, TunnelServerConfig, ControlHandler, accept_all_tokens};

async fn handle_client(stream: tokio::net::TcpStream, addr: std::net::SocketAddr) {
    let registry = Arc::new(TunnelRegistry::default());
    let config = TunnelServerConfig::default();
    let validator = Arc::new(accept_all_tokens);

    let handler = ControlHandler::new(registry, config, validator);
    if let Err(e) = handler.handle_connection(stream, addr).await {
        tracing::error!("Connection error: {}", e);
    }
}

Implementations

impl ControlHandler

pub fn new( registry: Arc<TunnelRegistry>, config: TunnelServerConfig, token_validator: TokenValidator, ) -> Self

Create a new control handler

Arguments

• registry - The tunnel registry for managing tunnel state
• config - Server configuration
• token_validator - Function to validate authentication tokens

pub fn with_dns_registrar(self, registrar: DynTunnelDnsRegistrar) -> Self

Set the DNS registrar for registering tunnel services in overlay DNS

pub fn with_local_overlay_ip(self, ip: Ipv4Addr) -> Self

Set the local overlay IP for DNS registration

pub async fn handle_connection( &self, stream: TcpStream, client_addr: SocketAddr, ) -> Result<()>

Handle a new WebSocket connection

This is the main entry point for each tunnel client connection. It performs the following steps:

1. Upgrade TCP connection to WebSocket
2. Wait for and validate AUTH message
3. Register the tunnel in the registry
4. Run the main message loop until disconnection
5. Clean up the tunnel on disconnect

Arguments

• stream - The TCP stream to upgrade
• client_addr - The client’s socket address

Errors

Returns an error if:

• WebSocket upgrade fails
• Authentication times out or fails
• Token is invalid or already in use
• Connection is closed unexpectedly