API Reference

Core Interfaces

Configuration (Spec)

Interface	Description
ProtocolStack	User-facing configuration container for protocols and packet policy
Protocol	Base class for protocol configuration, extends Settings
PacketPolicy	Controls packet acquisition, binding, and lifecycle
PacketPoolSettings	Configuration for packet pool capacity and sizing
PoolPolicy	Resource protection policy for pool-managed objects

Resolved (ResolvedSpec)

Interface	Description
ProtocolTree	Validated, immutable protocol structure template
ProtocolNode	Node in the protocol tree with routing rules
ResolvedPacketPolicy	Validated packet policy with backend constraints applied

Runtime (RuntimeSpec)

Interface	Description
ProcessorTree	Executable processor tree, one per stream
Processor	Protocol processing unit with state management
Router	Routes packets to downstream processors
Analyzer	Optional analysis attachment for token emission
RuntimePacketPolicy	Operational packet policy with acquire/release

Context

Interface	Description
ProcessorContext	Per-packet processing state with payload view
LayerContext	Per-layer extracted fields (IpContext, TcpContext)
BackendContext	Backend capabilities and constraints
StreamContext	Stream-specific context for building runtime

Output

Interface	Description
Packet	Processed packet with attached tokens
Token	Analysis result with 16-byte header + extensions
ProtocolObject	Protocol-specific output (IpDatagram, TcpSegment)

ProtocolStack

Primary configuration container for protocol processing.

public class ProtocolStack implements Spec {
    
    // Protocol configuration
    <T extends Protocol> T setProtocol(T protocol);
    <T extends Protocol> T setProtocol(T protocol, int depth);
    <T extends Protocol> T getProtocol(Class<T> type);
    <T extends Protocol> T getProtocol(Class<T> type, int depth);
    
    // Packet policy
    <T extends PacketPolicy> T setPacketPolicy(T policy);
    PacketPolicy getPacketPolicy();
    
    // Layer control
    void enable(Class<? extends Protocol> type);
    void disable(Class<? extends Protocol> type);
    void disableLayer(Class<? extends LayerMarker> layer);
    
    // Token subscription
    void subscribeTokens(int layerId, long tokenMask);
    
    // State management
    void clearState();
    void setQuietMode(boolean quiet);
}

Usage

ProtocolStack stack = new ProtocolStack();

stack.setProtocol(new IpProtocol())
     .enableReassembly(true)
     .fragmentTimeout(30);

stack.setProtocol(new TcpProtocol())
     .enableReassembly(true);

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

PacketPolicy

Controls packet acquisition, memory management, and lifecycle.

public interface PacketPolicy extends Spec, PacketPoolPolicy {
    
    // Configuration
    PacketPolicy usePacketPool(PacketPoolSettings settings);
    PacketPolicy descriptorType(DescriptorTypeInfo type);
    PacketPolicy dissectorDepth(int maxLayer);
    PacketPolicy clonePolicy(PacketPolicy policy);
    PacketPolicy descriptorPolicy(PoolPolicy policy);
    PacketPolicy memoryPolicy(PoolPolicy policy);
    
    // Characteristics
    DescriptorTypeInfo descriptorType();
    boolean isZeroCopy();
    boolean allowsCloning();
    
    // Factory methods
    static PacketPolicy zeroCopy();
    static PacketPolicy memoryCopy();
    static PacketPolicy factoryCopy();
}

RuntimePacketPolicy

public interface RuntimePacketPolicy extends RuntimeSpec {
    
    Packet acquire(MemorySegment hdr, MemorySegment data, int descriptorType);
    void dissect(Packet packet, int l2Type);
    void release(Packet packet);
    
    int capacity();
    int available();
}

Policy Types

Factory Method	Memory Strategy	Use Case
zeroCopy()	Bind to native memory	High-speed capture, short-lived packets
memoryCopy()	Copy to pool buffers	Packet persistence, cross-thread passing
factoryCopy()	Custom allocator	Arena-based allocation, special requirements

Protocol

Base class for protocol-specific configuration. Extends Settings for layered resolution.

public abstract class Protocol extends Settings {
    
    protected Protocol(String baseName);
    
    // Common to all protocols
    Protocol enabled(boolean enable);
    Protocol decap();
    boolean isEnabled();
    boolean isDecap();
}

Built-in Protocol Classes

Class	Layer	Key Settings
IpProtocol	L3	enableReassembly(), fragmentTimeout(), tableSize()
TcpProtocol	L4	enableReassembly(), maxOutOfOrder(), windowSize()
UdpProtocol	L4	Basic configuration
TlsProtocol	L5	enableDecryption(), keyLogFile()
HttpProtocol	L5	maxHeaderSize(), enableDecompression()
VlanProtocol	L2	decap() for VLAN stripping
GreProtocol	L3	decap() for tunnel termination

Settings Resolution Order

1. Explicit value (fluent setter)

2. System property (-Dprotocol.ip.reassembly.enabled=true)

3. Environment variable (PROTOCOL_IP_REASSEMBLY_ENABLED=true)

4. Loaded configuration file

5. Pack defaults (from protocol module JAR)

6. Coded default

Processor

Protocol processing unit within the processor tree.

public interface Processor {
    
    // Processing
    Packet processPacket(Packet packet, ProcessorContext ctx, LayerContext layer);
    ProtocolObject processProtocol(ProcessorContext ctx, LayerContext layer);
    
    // Analyzer
    void setAnalyzer(Analyzer analyzer);
    
    // State management
    void clearState();
    void clearFlow(long flowHash);
    void clearOlderThan(long timestampNs);
    
    // Timer
    void tick(long nowNs);
    void flush(Consumer<ProtocolObject> emit);
    
    // Statistics
    ProcessorStats stats();
}

Token

Analysis result container with compact binary format.

Token Header (16 bytes)

Offset	Size	Field
0	8	timestamp_ns
8	4	token_id (packed bits)
12	3	total_length
15	1	hdr_len (8-byte words)

Token ID Bit Layout

[1 flag][2 severity][2 level][6 flags][8 pack][13 index]
   31     30----29   28---27  26---21  20--13  12-----0

Common Token Types

Pack	Tokens
PACK_CORE	Flow boundary, reassembly status
PACK_TCP	TCP state changes, retransmissions
PACK_TLS	Handshake events, cipher info
PACK_IDS	IDS/IPS alerts
PACK_INDEX	Sparse/dense index beacons

Analyzer

Optional analysis attachment for processors.

public interface Analyzer {
    
    void analyze(ProcessorContext ctx, LayerContext layer);
    
    void setTokenMask(long mask);
    long supportedTokens();
    
    int priority();
    
    void initialize(AnalyzerConfig config);
    void shutdown();
    
    AnalyzerStats stats();
}

Router

Routes packets to downstream processors.

public interface Router {
    
    Processor route(LayerContext context);
    
    void addRoute(RoutingKey key, Processor target);
    void addHeuristic(ProtocolHeuristic heuristic);
    
    boolean isMutable();
}

Routing Lookup Order

1. Flow cache (runtime detection results)

2. Tunnel/VLAN context override

3. Domain context override

4. Global defaults (protocol field / port)

5. Heuristics (payload inspection)

6. Catch-all or null

Layer Markers

Interfaces for protocol layer classification.

public interface LayerMarker {}
public interface L2Protocol extends LayerMarker {}  // Ethernet, VLAN
public interface L3Protocol extends LayerMarker {}  // IP, ICMP
public interface L4Protocol extends LayerMarker {}  // TCP, UDP
public interface L5Protocol extends LayerMarker {}  // TLS, HTTP

Usage

// Disable all application layer protocols (for jNetPcap)
stack.disableLayer(L5Protocol.class);

SPI Services

PacketPolicyService

ResolvedPacketPolicy resolved = PacketPolicyService.resolve(policy, backendContext);
RuntimePacketPolicy runtime = PacketPolicyService.build(resolved, streamContext);

ProtocolStackService

ProtocolTree tree = ProtocolStackService.resolve(stack, backendContext);
ProcessorTree processors = ProtocolStackService.build(tree, streamContext);

ProtocolProvider

Protocol protocol = ProtocolProvider.lookupProtocol(IpProtocol.class);
Protocol protocol = ProtocolProvider.lookupProtocol(protocolId);

Javadoc

Full API documentation is available at:

• sdk-protocol-core Javadoc

• sdk-protocol-tcpip Javadoc

• sdk-protocol-web Javadoc