BPF-style pre-filtering in the Rust layer for high-performance packet filtering.

This module provides filters that are applied in the Rust layer before packets are deserialized to Elixir terms, resulting in 10-100x performance improvements for selective filtering on large files.

Important Notes

File Format Auto-Detection: If you get an error like "Invalid field value: PcapHeader: wrong magic number", your file might be PCAPNG format despite having a .pcap extension. Use PcapFileEx.open/1 for auto-detection instead of Pcap.open/1 or PcapNg.open/1.

# ✓ RECOMMENDED: Auto-detect format
{:ok, reader} = PcapFileEx.open("capture.pcap")

# ✗ AVOID: Manual format selection (unless you're sure)
{:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")  # Fails if actually PCAPNG

Filter Types

IP Filters

• ip_source/1 - Match source IP address
• ip_dest/1 - Match destination IP address
• ip_source_cidr/1 - Match source IP in CIDR range
• ip_dest_cidr/1 - Match destination IP in CIDR range

Port Filters

• port_source/1 - Match source port
• port_dest/1 - Match destination port
• port_source_range/2 - Match source port in range
• port_dest_range/2 - Match destination port in range

Protocol Filters

• protocol/1 - Match protocol (tcp, udp, icmp, ipv4, ipv6, etc.)

Size Filters

• size_min/1 - Match minimum packet size
• size_max/1 - Match maximum packet size
• size_range/2 - Match packet size in range

Timestamp Filters

• timestamp_min/1 - Match packets after timestamp (Unix seconds)
• timestamp_max/1 - Match packets before timestamp (Unix seconds)

Logical Operators

• all/1 - All filters must match (AND)
• any/1 - Any filter can match (OR)
• not_filter/1 - Invert filter (NOT)

Examples

# Filter TCP packets on port 80
filters = [
  PcapFileEx.PreFilter.protocol("tcp"),
  PcapFileEx.PreFilter.port_dest(80)
]

{:ok, reader} = PcapFileEx.Pcap.open("capture.pcap")
:ok = PcapFileEx.Pcap.set_filter(reader, filters)

# Now reading will only return matching packets
PcapFileEx.Stream.from_reader(reader)
|> Enum.take(10)

# Filter by IP range
filters = [
  PcapFileEx.PreFilter.ip_source_cidr("192.168.1.0/24"),
  PcapFileEx.PreFilter.size_range(100, 1500)
]

# Combine filters with logical operators
filters = [
  PcapFileEx.PreFilter.any([
    PcapFileEx.PreFilter.port_dest(80),
    PcapFileEx.PreFilter.port_dest(443)
  ])
]

Performance

Pre-filters are significantly faster than post-processing filters because:

• Packets are filtered in Rust before creating Elixir terms
• No memory allocation for filtered-out packets
• Reduced garbage collection pressure
• Lower CPU usage (no unnecessary protocol parsing)

For large files with selective filtering (e.g., "show me 10 packets on port 80 from a 10GB capture"), pre-filters can be 10-100x faster than post-processing.