Protocol Processing

jNetWorks and jNetPcap share an advanced protocol processing engine designed for high-performance, scalable analysis. This section covers key mechanisms for customization, optimization, and extension.

Specification Lifecycle Pattern

All configurable components follow a three-stage lifecycle for safe, efficient configuration and runtime instantiation:

• Spec: User-facing mutable configuration (e.g., ProtocolStack, PacketPolicy). Fluent API, may have unset values.

• ResolvedSpec: Immutable, validated form (e.g., ProtocolTree, ResolvedPacketPolicy). Defaults resolved, backend constraints applied.

• RuntimeSpec: Operational instance (e.g., ProcessorTree, RuntimePacketPolicy). Resources allocated, stateful, hot-path ready.

Transition methods (via SPI):

• resolve(Spec, BackendContext) → ResolvedSpec

• build(ResolvedSpec, StreamContext) → RuntimeSpec

This pattern ensures configurations are portable across backends while allowing hardware-specific optimizations.

Router and Heuristics

The routing system determines how packets flow through protocol processors, supporting complex encapsulation and tunneling.

Routing lookup order:

1. Flow cache (runtime detection for stateful flows)

2. Tunnel/VLAN context override (depth-aware)

3. Domain context override (e.g., custom rules)

4. Global defaults (protocol/port fields)

5. Heuristics (payload inspection via SPI plugins)

6. Catch-all (fallback processor)

Heuristics are registered via SPI (HeuristicProvider) and ordered by priority. Examples: signature matching for unknown ports, entropy analysis for encryption detection.

Analyzer Subsystem

Analyzers are optional plugins that attach to protocols and emit tokens without modifying packet flow. They are disabled at zero cost (bitmask pruning) when no subscribers are present.

• Attachment: Analyzers bind to specific layers (e.g., TCP_LAYER) via SPI (AnalyzerProvider).

• Priority: Ordered execution within layers (pre/post processing).

• Output: Emit tokens for events like anomalies, ML inferences, or alerts.

• Pruning: If no token subscriptions match an analyzer's output, it's skipped entirely.

Example: IDS analyzer scanning for signatures, emitting ALERT tokens.

Token Subsystem

Tokens are lightweight (16-byte base + optional extensions) analysis results attached directly to packets for unified output.

Token ID structure: [1 flag][2 severity][2 level][6 flags][8 pack][13 index]

Key packs:

• CORE (0x0000): flow boundaries, reassembly complete/incomplete

• TCP (0x0100): state changes, retransmits

• TLS (0x0200): handshake events

• IDS (0x1000): alerts with severity

• ANOMALY (0x2000): unusual patterns

• ML (0x3000): inference results

• INDEX (0x4000): indexing beacons

• USER (0xF000): custom extensions

Subscribe via stack.subscribeTokens(LAYER, TOKEN_MASK) to enable generation.

Packet Policy

Controls how packets are handled, allocated, and released. Redesigned in v3.1 for pool-managed efficiency.

Policies:

• ZeroCopyPacketPolicy: Direct native buffer reference (fastest, but read-only).

• MemoryCopyPacketPolicy: Copy to managed memory (safer for modifications).

• FactoryCopyPacketPolicy: Use custom factory for packet instances.

Example:

stack.setPacketPolicy(PacketPolicy.zeroCopy())
     .usePacketPool(new PacketPoolSettings().capacity(100_000));

Resolved via PacketPolicyService.resolve(policy, backend) to validate backend compatibility.

Pool Policy

Protects shared resources with fixed or mutable pools.

• FixedPoolPolicy: Strict limits, blocks on exhaustion (predictable memory use).

• MutablePoolPolicy: Dynamic resizing, evicts on pressure (flexible for variable loads).

Applied to views, descriptors, tokens, etc.:

policy.descriptorPolicy(PoolPolicy.fixed(10_000));

Pre-bound Packet Optimization

For zero-allocation hot paths, packets are pre-bound from pools:

• Allocate from view pool (CAS free list)

• Bind data memory and descriptor references

• Process (no new allocations)

• Release back to pool (CAS)

This eliminates GC pressure in sustained high-throughput scenarios.

Backend Substitution

Allows hardware offload by substituting processors:

• Backend provides capabilities via BackendContext

• During resolve(), incompatible specs are adjusted or rejected

• In build(), runtime processors may be replaced with hardware equivalents

Example: IP reassembly offloaded to Napatech hardware.

SPI and Extensions

Consistent SPI across domains:

• ProtocolStackService: resolve/stack to tree, build/tree to processors

• PacketPolicyService: resolve/validate policy, build/runtime policy

• AnalyzerProvider: Register custom analyzers

• HeuristicProvider: Custom protocol detection

Implement and register in META-INF/services.

Hot Path Principles

Strict rules enforced:

1. Zero allocation - Rebind, pool, reuse.

2. No exceptions - Counters for errors.

3. No callbacks - Direct calls only.

4. No locks - Single-threaded per ProcessorTree.

5. Array/switch routing - No maps.

6. Bitmask pruning - Disabled features cost zero.

7. Pre-binding - All objects ready before hot path.

VarHandle for field access ensures near-native speed.

Next Steps

• Packet Policy – Dive deeper into allocation strategies

• Tutorials – See advanced features in action

• API Reference – Full class listings

These features make the protocol engine extensible while maintaining wire-speed performance.