pktkit 0.1.0

Zero-copy L2/L3 packet handling toolkit. Frames, packets, hubs, adapters, NAT, virtual TCP/IP, WireGuard, OpenVPN, QEMU networking, TUN/TAP, AF_XDP — all gated behind opt-in cargo features.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

use crate::{Frame, IpPrefix, MacAddr, Packet, Result};
use std::sync::Arc;

/// 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.
pub type L2Handler = Arc<dyn Fn(&Frame) -> Result<()> + Send + Sync + 'static>;

/// 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.
pub type L3Handler = Arc<dyn Fn(&Packet) -> Result<()> + Send + Sync + 'static>;

/// A generic handler over any borrowed message type.
///
/// Most users will want [`L2Handler`] or [`L3Handler`] instead.
pub type Handler<T> = Arc<dyn Fn(&T) -> Result<()> + Send + Sync + 'static>;

/// A Layer 2 (Ethernet) network device.
///
/// Implementors must call the handler set by [`set_handler`](Self::set_handler)
/// whenever a frame is received. [`send`](Self::send) may be invoked from any
/// thread; implementations are responsible for any internal synchronization.
///
/// The `&Frame` passed to either method is only valid for the duration of the
/// call — clone the bytes if you need to keep them.
pub trait L2Device: Send + Sync {
    /// Install or replace the handler invoked on every received frame.
    fn set_handler(&self, h: L2Handler);

    /// Transmit a frame on the device.
    fn send(&self, frame: &Frame) -> Result<()>;

    /// The device's hardware address.
    fn hw_addr(&self) -> MacAddr;

    /// Release any resources held by the device.
    fn close(&self) -> Result<()>;
}

/// A Layer 3 (IP) network device.
///
/// `Addr` returns the device's current IP prefix; `set_addr` updates it,
/// typically from a DHCP client or other source of dynamic configuration.
pub trait L3Device: Send + Sync {
    fn set_handler(&self, h: L3Handler);
    fn send(&self, packet: &Packet) -> Result<()>;

    fn addr(&self) -> IpPrefix;
    fn set_addr(&self, prefix: IpPrefix) -> Result<()>;

    fn close(&self) -> Result<()>;
}

// Blanket impls so callers can store devices as `Arc<dyn L2Device>` or
// `Box<dyn L2Device>` without rewriting the trait surface.

impl<T: L2Device + ?Sized> L2Device for Arc<T> {
    #[inline]
    fn set_handler(&self, h: L2Handler) {
        (**self).set_handler(h)
    }
    #[inline]
    fn send(&self, f: &Frame) -> Result<()> {
        (**self).send(f)
    }
    #[inline]
    fn hw_addr(&self) -> MacAddr {
        (**self).hw_addr()
    }
    #[inline]
    fn close(&self) -> Result<()> {
        (**self).close()
    }
}

impl<T: L3Device + ?Sized> L3Device for Arc<T> {
    #[inline]
    fn set_handler(&self, h: L3Handler) {
        (**self).set_handler(h)
    }
    #[inline]
    fn send(&self, p: &Packet) -> Result<()> {
        (**self).send(p)
    }
    #[inline]
    fn addr(&self) -> IpPrefix {
        (**self).addr()
    }
    #[inline]
    fn set_addr(&self, p: IpPrefix) -> Result<()> {
        (**self).set_addr(p)
    }
    #[inline]
    fn close(&self) -> Result<()> {
        (**self).close()
    }
}