Stackforge Core

High-performance, zero-copy network packet manipulation library.

This crate provides the core networking primitives for the Stackforge framework, implementing a "Lazy Zero-Copy View" architecture for efficient packet processing.

Architecture

Unlike traditional packet parsing libraries that eagerly deserialize all fields into objects, Stackforge Core uses a lazy evaluation model:

1. Zero-Copy Buffers: Packets are stored as contiguous byte buffers using the bytes crate's reference-counted Bytes type.

2. Index-Only Parsing: When parsing a packet, we only identify layer boundaries (where each protocol header starts and ends).

3. On-Demand Access: Field values are read directly from the buffer only when explicitly requested.

4. Copy-on-Write: Mutation triggers buffer cloning only when shared.

Example

use stackforge_core::{Packet, LayerKind, EthernetLayer, ArpBuilder};
use stackforge_core::layer::field::MacAddress;
use std::net::Ipv4Addr;

// Build an ARP request
let arp = ArpBuilder::who_has(Ipv4Addr::new(192, 168, 1, 100))
    .hwsrc(MacAddress::new([0x00, 0x11, 0x22, 0x33, 0x44, 0x55]))
    .psrc(Ipv4Addr::new(192, 168, 1, 1))
    .build();

// Parse an existing packet
let raw_bytes = vec![
    0xff, 0xff, 0xff, 0xff, 0xff, 0xff,  // Destination MAC (broadcast)
    0x00, 0x11, 0x22, 0x33, 0x44, 0x55,  // Source MAC
    0x08, 0x06,                          // EtherType: ARP
];

let eth = EthernetLayer::at_start();
assert_eq!(eth.ethertype(&raw_bytes).unwrap(), 0x0806);