Crate pktkit 

Zero-copy L2/L3 packet handling toolkit.

pktkit provides primitives for building virtual network topologies: devices, hubs, adapters, NAT, and tunnels that move Ethernet frames and IP packets without copying buffers on the hot path.

See the crate-level README for a tour of what each Cargo feature adds. The default build ships only the core types — everything else is opt-in.

Core

• Frame is an Ethernet frame; Packet is an IP packet. Both are #[repr(transparent)] newtypes over [u8] so &Frame is the same shape as &[u8] and accessors are free.
• L2Device and L3Device are object-safe traits for anything that sends/receives frames or packets. Forwarding is a synchronous callback; the buffer is only valid for the duration of the call.
• L2Hub is a MAC-learning switch with 5-minute aging. L3Hub is a prefix-routing hub with a default route fallback.
• PipeL2 and PipeL3 are in-memory devices for tests and for wiring subpackages together.
• connect_l2 and connect_l3 wire two devices point-to-point.
• serve runs an accept loop, joining each incoming L2 device into a connector.

Modules

afxdpafxdp

Linux AF_XDP zero-copy sockets.

arpl2adapter

ARP (RFC 826) for IPv4 over Ethernet.

dhcpdhcp

DHCP wire codec, client state machine, and server.

natnat

Packet-level network address translation.

ndpl2adapter

NDP (RFC 4861): neighbor cache + Neighbor Solicitation/Advertisement codec for IPv6.

ovpnovpn

OpenVPN server.

qemuqemu

QEMU userspace network socket protocol.

slirpslirp

Userspace NAT stack (userspace SLIRP-style routing).

tuntaptuntap

OS-level TUN and TAP devices.

vclientvclient

High-level virtual network client.

vtcpvtcp

Virtual TCP engine.

wgwg

WireGuard tunnel: Noise IKpsk2 handshake + ChaCha20-Poly1305 transport.

Structs

BufferPool

A thread-safe buffer pool for packet/frame storage.

EtherType

EtherType identifies the protocol encapsulated in an Ethernet frame payload.

Frame

A raw Ethernet frame.

IpPrefix

An IP address with a CIDR prefix length.

L2Adapterl2adapter

Bridges an L3 device onto an L2 network.

L2AdapterConfigl2adapter

Configure an L2Adapter.

L2Hub

A learning Ethernet switch.

L2HubHandle

Returned by L2Hub::connect; dropping or calling close detaches the device.

L3Hub

A routing hub that forwards IP packets between connected devices.

L3HubHandle

Returned by L3Hub::connect; dropping or calling close detaches the device.

MacAddr

A 48-bit Ethernet MAC address.

Packet

A raw IP packet (no Ethernet header).

PipeL2

A simple in-memory L2Device useful for tests and for wiring subpackages.

PipeL3

A simple in-memory L3Device useful for tests.

Protocol

Protocol identifies the IP protocol number carried in an IP packet.

Constants

BROADCAST_MAC

The all-ones broadcast MAC, ff:ff:ff:ff:ff:ff.

DEFAULT_MTU

Default packet buffer size — enough for an Ethernet MTU plus a little headroom for tunnel overlays.

Traits

Done

A blocking signal raised when a peer connection is fully closed. The connector uses this to release per-peer resources.

DoneSignal

A device that signals when its connection has terminated.

L2Acceptor

Produces L2Devices, typically by accepting incoming network connections.

L2AcceptorWithDone

Variant of L2Acceptor that yields an optional connection-closed signal alongside each device.

L2Connector

Receives L2Devices and owns their attachment lifecycle.

L2Device

A Layer 2 (Ethernet) network device.

L3Connector

Receives L3Devices and owns their attachment lifecycle.

L3Device

A Layer 3 (IP) network device.

Functions

build_frame

Allocate and return a new Ethernet frame with the given header fields and payload. The result is a Vec<u8>; borrow it as &Frame via Frame::from_slice.

checksum

Compute the Internet checksum (RFC 1071) over data.

combine_checksums

Fold two complemented Internet checksums into a single combined value.

connect_l2

Wire two L2Devices point-to-point: frames produced by one are delivered to the other.

connect_l3

Wire two L3Devices point-to-point.

pseudo_header_checksum

Compute the pseudo-header checksum for TCP/UDP, dispatching on the address family. Returns the complemented sum, ready to feed into combine_checksums with the payload checksum.

serve

Accept loop: receive devices from acceptor and attach each one to connector. If a device implements DoneSignal, its cleanup is invoked automatically when the remote end disconnects.

serve_with_done

Like serve, but the acceptor returns (device, optional done signal) pairs so cleanup can be triggered when the connection drops. Use this when your acceptor implementation knows when a peer disconnects.

Type Aliases

Cleanup

A cleanup function returned by a Connector implementation. Calling it detaches the device that was attached and releases any per-device resources.

Handler

A generic handler over any borrowed message type.

L2Handler

A frame handler: invoked synchronously by an L2Device when a frame is received. The &Frame borrow is valid only for the duration of the call; callers that need to retain the bytes must copy them.

L3Handler

A packet handler: invoked synchronously by an L3Device when a packet is received. The &Packet borrow is valid only for the duration of the call.

Result

Crate-wide Result alias.