Struct SnapTunServer 

pub struct SnapTunServer<T: SnapTunAuthorization> { /* private fields */ }

The SnapTunServer manages one Tunn per remote socket address.

The main structural difference between WireGuard (R) and snaptun-ng is that there is a one-to-one relation between a remote socket address (of the initiator) and a tunnel. The SnapTunServer manages that relation.

Scaling

The main methods SnapTunServer::handle_incoming_packet, SnapTunServer::handle_outgoing_packet, and SnapTunServer::update_timers all require an exclusive reference to the internal state. The reason is that processing both, incoming and outgoing packets requires access to the session state.

One simple way to achieve load distribution across different cores/threads is to shard over multiple SnapTunServer-instances based on a hash of the remote socket address.

Future improvements

• Separate incoming and outgoing code paths and optimistically lock the session state.

How to use

The SnapTunServer is i/o-free; i.e. it only manages state. The following is a pseudo-code like description of the simplest i/o-layer integration:

let mut server = SnapTunServer::new(/*...*/);
let mut send_to_network = VecDequeue::new();
let mut current_sockaddr = ;
loop {
  switch {
    (network_packet, sockaddr) = network_socket => {
      server.handle_incoming_packet(/*...*/);
      /* dispatch packets to tunnel if necessary */
    }
    tunnel_packet = tunnel_socket => {
      server.handle_outgoing_packet(/*...*/);
    }
    timer = tick(250ms) => {
      server.update_timers();
    }
  }
  // dispatch packets to network
  for p in send_to_network {
    network_socket.send(sockaddr, p);
  }
}

Implementations

impl<T: SnapTunAuthorization> SnapTunServer<T>

pub fn new( static_private: StaticSecret, rate_limiter: Arc<RateLimiter>, authz: Arc<T>, ) -> Self

Creates a new SnapTunServer instance.

pub fn handle_incoming_packet( &mut self, packet: Packet, from: SocketAddr, send_to_network: &mut VecDeque<WgKind>, ) -> TunnResult

Handle incoming packet for a tunnel assocated with remote socket address from.

This method never returns TunnResult::WriteToNetwork. Instead, it codifies the expected protocol behavior which is that, upon receiving a packet from the remote, the queue of outgoing packets is completely drained.

If the rate limiter signals that the server is under load, at most one packet is added to the queue.

This compatibility wrapper preserves the original public API for callers that only care about the tunnel result.

pub fn handle_incoming_packet_with_session( &mut self, packet: Packet, from: SocketAddr, send_to_network: &mut VecDeque<WgKind>, ) -> HandleIncomingPacketResult<T::SessionData>

Handles an incoming packet and also returns the active session when one was resolved while processing the packet.

Callers on the dataplane hot path can use this to observe forwarded packets without re-hashing from for a second active-tunnel lookup, while existing callers can keep using SnapTunServer::handle_incoming_packet.

pub fn handle_outgoing_packet( &mut self, packet: Packet, to: SocketAddr, ) -> Option<WgKind>

Handles an outgoing packet sent through the tunnel identified by the remote socket address to.

pub fn handle_outgoing_packet_with_session( &mut self, packet: Packet, to: SocketAddr, ) -> Option<HandleOutgoingPacketResult<T::SessionData>>

Handles an outgoing packet and returns the active tunnel session used to admit the payload into the tunnel pipeline.

This re-checks authorization on the outgoing path. If the active tunnel no longer has current authorization, the packet is dropped and None is returned even when the tunnel state itself still exists.

pub fn update_timers(&mut self) -> Vec<(SocketAddr, WgKind)>

Update timers of all tunnels. Generate corresponding keepalive or session handshake initializations.

As a result of this call, all expired tunnels are removed. Note that this is not the same as unauthorized tunnels.

Callers are expected to invoke this periodically; it is also where the rate limiter’s under-load counter is reset. Without that reset the counter only ever grows and the server eventually treats itself as permanently under load.