Crate stackforge_core 

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);

Re-exports

pub use error::PacketError;

pub use error::Result;

pub use layer::arp::ARP_FIXED_HEADER_LEN;

pub use layer::arp::ARP_HEADER_LEN;

pub use layer::arp::ArpRoute;

pub use layer::arp::HardwareAddr;

pub use layer::arp::ProtocolAddr;

pub use layer::bindings::BindingRegistry;

pub use layer::bindings::apply_binding;

pub use layer::bindings::expected_upper_layers;

pub use layer::bindings::find_binding;

pub use layer::bindings::find_bindings_from;

pub use layer::bindings::find_bindings_to;

pub use layer::bindings::infer_upper_layer;

pub use layer::ethernet::DOT3_MAX_LENGTH;

pub use layer::ethernet::ETHERNET_HEADER_LEN;

pub use layer::ethernet::EthernetFrameType;

pub use layer::ethernet::dispatch_hook;

pub use layer::ethernet::is_dot3;

pub use layer::ethernet::is_ethernet_ii;

pub use layer::neighbor::ArpCache;

pub use layer::neighbor::CacheEntry;

pub use layer::neighbor::NdpCache;

pub use layer::neighbor::ipv4_multicast_mac;

pub use layer::neighbor::ipv6_multicast_mac;

pub use layer::neighbor::is_ipv4_multicast;

pub use layer::neighbor::is_ipv6_multicast;

pub use layer::neighbor::solicited_node_multicast;

pub use layer::quic::builder::QuicBuilder;

pub use layer::ArpBuilder;

pub use layer::ArpLayer;

pub use layer::BytesField;

pub use layer::DnsLayer;

pub use layer::Dot3Builder;

pub use layer::Dot3Layer;

pub use layer::EthernetBuilder;

pub use layer::EthernetLayer;

pub use layer::Field;

pub use layer::FieldDesc;

pub use layer::FieldError;

pub use layer::FieldType;

pub use layer::FieldValue;

pub use layer::Http2Builder;

pub use layer::Http2FrameBuilder;

pub use layer::HttpRequestBuilder;

pub use layer::HttpResponseBuilder;

pub use layer::ICMPV6_MIN_HEADER_LEN;

pub use layer::IPV6_HEADER_LEN;

pub use layer::IcmpBuilder;

pub use layer::IcmpLayer;

pub use layer::Icmpv6Builder;

pub use layer::Icmpv6Layer;

pub use layer::IntoLayerStackEntry;

pub use layer::Ipv4Builder;

pub use layer::Ipv4Flags;

pub use layer::Ipv4Layer;

pub use layer::Ipv6Builder;

pub use layer::Ipv6Layer;

pub use layer::L2TP_FIELD_NAMES;

pub use layer::L2TP_MIN_HEADER_LEN;

pub use layer::L2TP_PORT;

pub use layer::L2tpBuilder;

pub use layer::L2tpLayer;

pub use layer::LAYER_BINDINGS;

pub use layer::Layer;

pub use layer::LayerBinding;

pub use layer::LayerEnum;

pub use layer::LayerIndex;

pub use layer::LayerKind;

pub use layer::LayerStack;

pub use layer::LayerStackEntry;

pub use layer::MacAddress;

pub use layer::NeighborCache;

pub use layer::NeighborResolver;

pub use layer::RAW_FIELDS;

pub use layer::RawBuilder;

pub use layer::RawLayer;

pub use layer::SSH_BINARY_HEADER_LEN;

pub use layer::SSH_PORT;

pub use layer::SshBuilder;

pub use layer::SshLayer;

pub use layer::TcpBuilder;

pub use layer::TcpFlags;

pub use layer::TcpLayer;

pub use layer::TlsRecordBuilder;

pub use layer::UdpBuilder;

pub use layer::UdpLayer;

pub use layer::icmpv6_checksum;

pub use layer::verify_icmpv6_checksum;

pub use packet::Packet;

pub use pcap::CapturedPacket;

pub use pcap::LinkType;

pub use pcap::PcapIterator;

pub use pcap::PcapMetadata;

pub use pcap::rdpcap;

pub use pcap::wrpcap;

pub use pcap::wrpcap_packets;

pub use flow::CanonicalKey;

pub use flow::ConversationState;

pub use flow::ConversationStatus;

pub use flow::ConversationTable;

pub use flow::DirectionStats;

pub use flow::FlowConfig;

pub use flow::FlowDirection;

pub use flow::FlowError;

pub use flow::ProtocolState;

pub use flow::TransportProtocol;

pub use flow::extract_flows;

pub use flow::extract_flows_with_config;

pub use utils::align_to;

pub use utils::ethernet_min_frame;

pub use utils::extract_bits;

pub use utils::hexdump;

pub use utils::hexstr;

pub use utils::hexstr_sep;

pub use utils::internet_checksum;

pub use utils::pad_to;

pub use utils::parse_hex;

pub use utils::set_bits;

pub use utils::transport_checksum;

pub use utils::verify_checksum;

Modules

arp_hardware

ARP hardware types.

arp_opcode

ARP operation codes.

arp_protocol

ARP protocol types.

error

Error types for the stackforge-core crate.

ethertype

Protocol constants for EtherType field.

flow

Stateful conversation extraction and flow tracking.

ip_protocol

Protocol constants for IP protocol numbers.

layer

Layer definitions and enum dispatch for protocol handling.

packet

Zero-copy packet representation and manipulation.

pcap

PCAP file I/O for reading and writing packet captures.

prelude

Prelude module for convenient imports.

utils

Utility functions for packet manipulation.

Constants

VERSION

Version information

Functions

version

Get library version