Crate tunnel_lattice 

Cross-platform Rust library for TUN/TAP tunnel interfaces, designed to compose with the rest of the Lattice networking stack.

Start with Tunnel::connect (available with the default tun-rs feature) to open a device:

use tunnel_lattice::{DeviceConfig, DeviceKind, Result, Tunnel};

fn main() -> Result<()> {
    let tunnel = Tunnel::connect();
    let device = tunnel.open(DeviceConfig::new(DeviceKind::Tun).with_mtu(1500))?;
    let mut buf = vec![0u8; 1500];
    let len = device.recv(&mut buf)?;
    println!("{} bytes", len);
    Ok(())
}

This crate carries no OS-addressing responsibility — it creates and configures the virtual interface and transfers packets on it; IP address assignment on the resulting interface is net-lattice’s job (see the net-lattice crate in the sibling Lattice ecosystem).

Feature flags

• tun-rs (default): selects tunnel-lattice-backend-tunrs, implemented on top of the cross-platform tun-rs crate. This is a Cargo feature rather than a target_os cfg gate so a future alternative backend can sit alongside it instead of replacing it — see the workspace ARCHITECTURE.md, “Backend replacement plan.”
• async-io/tokio: mutually exclusive, matching tun-rs’s own two async backends (enabling both is a compile error). Either one adds Handle::packet_stream, a futures::Stream of received packets. Uses a backend’s native async I/O path when it reports Capability::NATIVE_ASYNC; otherwise falls back to tunnel-lattice-async’s thread-based adapter. No async runtime is forced on a caller that enables neither feature. packet_stream is referenced here as plain text, not an intra-doc link, because it only exists under these features and this crate’s default cargo doc build (no features beyond tun-rs) cannot resolve it.

Structs

Capability

Runtime-dependent backend features that cannot be expressed through Rust trait implementation alone.

Device

An observed, already-open TUN/TAP device.

DeviceConfig

Desired intent for creating a new TUN/TAP device.

DeviceConfigPatch

A patch requesting a change to an already-open Device’s MTU or administrative state.

Handle

An open TUN/TAP device.

Tunnel

A connected backend for creating and operating TUN/TAP devices.

Enums

AdminState

The administrative state of a device, as observed from the backend.

DesiredAdminState

The administrative state requested for a DeviceConfigPatch.

DeviceKind

Whether a device presents Ethernet-framed (TAP) or raw IP (TUN) packets.

Error

The single error type surfaced across the Tunnel Lattice workspace.

Traits

CapabilityProvider

Reports which runtime-dependent Capability flags the connected device currently has available.

ConnectedDevice

An open device handle bound to this facade’s concrete model types.

MultiQueueProvider

Duplicates an open device’s queue for use from another thread, when the backend and the running kernel support hardware-scheduled multiple queues on one device (Linux IFF_MULTI_QUEUE).

PersistentDevice

Marks an open device to survive process exit, so a later process requesting the same name can attach to it instead of creating a new one.

Type Aliases

DeviceId

Identifies a Device.

Result

A result returned by Tunnel Lattice operations.