pcapsql_core/
lib.rs

1//! # pcapsql-core
2//!
3//! Engine-agnostic PCAP protocol parsing library.
4//!
5//! This crate provides the core parsing functionality for pcapsql, without
6//! any SQL engine dependencies. It can be used standalone for protocol
7//! analysis or as the foundation for SQL integrations (DataFusion, DuckDB).
8//!
9//! ## Features
10//!
11//! - **Protocol Parsing**: 17 built-in protocol parsers (Ethernet, IP, TCP, UDP,
12//!   DNS, HTTP, TLS, DHCP, NTP, and more)
13//! - **PCAP Reading**: Support for PCAP and PCAPNG formats, including gzip/zstd
14//!   compression
15//! - **Memory-Mapped I/O**: Efficient reading of large capture files
16//! - **Parse Caching**: LRU cache to avoid redundant parsing during JOINs
17//! - **TCP Stream Reassembly**: Connection tracking and application-layer parsing
18//!
19//! ## Quick Start
20//!
21//! ```rust,no_run
22//! use pcapsql_core::prelude::*;
23//! use pcapsql_core::io::FilePacketSource;
24//!
25//! // Create a protocol registry with all built-in parsers
26//! let registry = default_registry();
27//!
28//! // Open a PCAP file
29//! let source = FilePacketSource::open("capture.pcap").unwrap();
30//! let mut reader = source.reader(None).unwrap();
31//!
32//! // Read and parse packets using callback pattern
33//! reader.process_packets(1000, |packet| {
34//!     let results = pcapsql_core::parse_packet(
35//!         &registry,
36//!         packet.link_type as u16,
37//!         &packet.data,
38//!     );
39//!
40//!     for (protocol_name, result) in results {
41//!         println!("{}: {} fields", protocol_name, result.fields.len());
42//!     }
43//!     Ok(())
44//! }).unwrap();
45//! ```
46//!
47//! ## Architecture
48//!
49//! ```text
50//! +---------------------------------------------------------------------+
51//! |                        pcapsql-core                                 |
52//! +---------------------------------------------------------------------+
53//! |  schema/     - FieldDescriptor, DataKind (engine-agnostic)          |
54//! |  protocol/   - Protocol trait, 17 parsers, FieldValue               |
55//! |  io/         - PacketSource, PacketReader, mmap support             |
56//! |  pcap/       - PCAP/PCAPNG reading, compression                     |
57//! |  cache/      - LRU parse cache                                      |
58//! |  stream/     - TCP reassembly, HTTP/TLS stream parsing              |
59//! |  format/     - Address formatting utilities                         |
60//! |  error/      - Error types                                          |
61//! +---------------------------------------------------------------------+
62//! ```
63//!
64//! ## Crate Features
65//!
66//! - `default` - Gzip and Zstd compression enabled
67//! - `compress-gzip` - Gzip decompression support
68//! - `compress-zstd` - Zstd decompression support
69//! - `compress-lz4` - LZ4 decompression support
70//! - `compress-bzip2` - Bzip2 decompression support
71//! - `compress-xz` - XZ decompression support
72//! - `compress-all` - All compression formats
73//!
74//! ## Supported Protocols
75//!
76//! | Layer | Protocols |
77//! |-------|-----------|
78//! | Link | Ethernet, VLAN (802.1Q) |
79//! | Network | IPv4, IPv6, ARP, ICMP, ICMPv6 |
80//! | Transport | TCP, UDP |
81//! | Application | DNS, DHCP, NTP, HTTP, TLS, SSH, QUIC |
82
83pub mod cache;
84pub mod error;
85pub mod format;
86pub mod io;
87pub mod pcap;
88pub mod prelude;
89pub mod protocol;
90pub mod schema;
91pub mod stream;
92pub mod tls;
93
94// Re-export commonly used types at crate root for convenience
95pub use cache::{CacheStats, CachedParse, LruParseCache, NoCache, OwnedParseResult, ParseCache};
96pub use error::{Error, PcapError, ProtocolError, Result};
97pub use format::{detect_address_column, format_ipv4, format_ipv6, format_mac, AddressKind};
98pub use io::{FilePacketReader, FilePacketSource, PacketReader, PacketSource, RawPacket};
99#[cfg(feature = "mmap")]
100pub use io::{MmapPacketReader, MmapPacketSource};
101pub use pcap::PcapReader;
102pub use protocol::OwnedFieldValue;
103pub use protocol::{
104    chain_fields_for_protocol, compute_required_protocols, default_registry,
105    merge_with_chain_fields, parse_packet, parse_packet_projected, parse_packet_pruned,
106    parse_packet_pruned_projected, should_continue_parsing, should_run_parser, BuiltinProtocol,
107    FieldValue, ParseContext, ParseResult, PayloadMode, ProjectionConfig, Protocol,
108    ProtocolRegistry, TunnelLayer, TunnelType,
109};
110pub use schema::{DataKind, FieldDescriptor, ProtocolSchema};
111pub use stream::{
112    Connection, ConnectionState, ConnectionTracker, Direction, ParsedMessage, StreamConfig,
113    StreamContext, StreamManager, StreamParseResult, StreamParser, StreamRegistry, TcpFlags,
114};
115pub use tls::{
116    derive_tls12_keys, derive_tls13_keys, extract_tls13_inner_content_type, hash_for_cipher_suite,
117    tls12_prf, AeadAlgorithm, DecryptionContext, DecryptionError, Direction as TlsDirection,
118    HandshakeData, HashAlgorithm, KeyDerivationError, KeyLog, KeyLogEntries, KeyLogEntry,
119    KeyLogError, SessionError, SessionState, Tls12KeyMaterial, Tls13KeyMaterial, TlsSession,
120    TlsVersion,
121};
122
123/// Library version.
124pub const VERSION: &str = env!("CARGO_PKG_VERSION");
pcapsql_core/lib.rs

pcapsql_core/
lib.rs
