Overview

Design Principles

• Packet-centric push model with dual return paths (processPacket and processProtocol)

• Zero-allocation fast path – Header instances are reused and rebound via hasHeader()

• Single-threaded per ProcessorTree – No internal locks, parallelism via multiple trees

• Pure configuration in ProtocolStack – Settings extend Settings with layered resolution

• Depth support for tunneled/encapsulated protocols (e.g., IP-in-IP, VLAN stacking)

• Decap pattern to simplify processing of nested encapsulations

• Token attachment – Analysis results travel with the packet for unified output

• Bitmask pruning – Analyzers disabled at zero cost when no subscribers

Three-Tier Architecture

The architecture consists of:

• ProtocolStack (user configuration)

• ProtocolTree (immutable template from SPI)

• ProcessorTree (runtime instance per stream)

Processing Model

Two entry methods:

• processPacket(Packet, ctx) → returns Packet (used by jNetPcap and jNetWorks PacketStreams)

• processProtocol(ProcessorContext) → returns ProtocolObject (used by ProtocolStreams/DataStreams)

Return contract:

• Non-null → deliver to downstream/user

• Null → consumed (e.g., buffered for reassembly)