SPI and Extensions

The protocol infrastructure uses Java's ServiceLoader mechanism for extensibility. This allows protocol packs, analyzers, and custom backends to be discovered and loaded at runtime.

Specification Lifecycle Services

All configurable components follow the Spec → ResolvedSpec → RuntimeSpec lifecycle with corresponding SPI services:

// Pattern for all domain services
ResolvedSpec resolved = DomainService.resolve(spec, backendContext);
RuntimeSpec runtime = DomainService.build(resolved, streamContext);

PacketPolicyService

Resolves and builds packet policies:

public interface PacketPolicyService {
    
    static ResolvedPacketPolicy resolve(PacketPolicy policy, BackendContext backend);
    static RuntimePacketPolicy build(ResolvedPacketPolicy resolved, StreamContext stream);
}

Usage:

// Typically called internally by frontend
ResolvedPacketPolicy resolved = PacketPolicyService.resolve(
    stack.getPacketPolicy(), 
    backendContext);

RuntimePacketPolicy runtime = PacketPolicyService.build(
    resolved, 
    streamContext);

// Now ready for hot-path operations
Packet packet = runtime.acquire(hdr, data, descriptorType);

ProtocolStackService

Resolves protocol stacks to trees and builds processor instances:

public interface ProtocolStackService {
    
    static ProtocolTree resolve(ProtocolStack stack, BackendContext backend);
    static ProcessorTree build(ProtocolTree tree, StreamContext stream);
}

Usage:

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

// Process packets
Packet result = processors.processPacket(packet, context);

Pack-Level Protocol Discovery

Protocols are discovered at the pack (module) level via ProtocolProvider:

public interface ProtocolProvider {
    
    // Pack identification
    int packId();        // PACK_TCPIP, PACK_WEB, etc.
    String packName();   // "tcpip", "web", "telco"
    
    // Protocol lookup
    Protocol findProtocol(int protocolId);
    <T extends Protocol> T findProtocol(Class<T> type);
}

Implementing a Protocol Provider

public class TcpIpProtocolProvider implements ProtocolProvider {
    
    // Load pack defaults on class initialization
    static {
        try (InputStream in = TcpIpProtocolProvider.class
                .getResourceAsStream("/tcpip-protocol-defaults.properties")) {
            if (in != null) {
                Settings.loadDefaults(in, "protocol");
            }
        } catch (IOException e) {
            // Log warning, continue with coded defaults
        }
    }
    
    @Override
    public int packId() { 
        return ProtocolId.PACK_TCPIP; 
    }
    
    @Override
    public String packName() { 
        return "tcpip"; 
    }
    
    @Override
    public Protocol findProtocol(int protocolId) {
        int index = ProtocolId.indexOf(protocolId);
        return switch (index) {
            case 0x21 -> new IpProtocol();
            case 0x40 -> new TcpProtocol();
            case 0x41 -> new UdpProtocol();
            default -> null;
        };
    }
    
    @Override
    @SuppressWarnings("unchecked")
    public <T extends Protocol> T findProtocol(Class<T> type) {
        if (type == IpProtocol.class) return (T) new IpProtocol();
        if (type == TcpProtocol.class) return (T) new TcpProtocol();
        if (type == UdpProtocol.class) return (T) new UdpProtocol();
        return null;
    }
}

Service Registration

Create file META-INF/services/com.slytechs.sdk.protocol.spi.ProtocolProvider:

com.slytechs.sdk.protocol.tcpip.spi.TcpIpProtocolProvider

Static Lookup Methods

// By class
IpProtocol ip = ProtocolProvider.lookupProtocol(IpProtocol.class);

// By ID (routes to correct pack based on pack ID in protocol ID)
Protocol proto = ProtocolProvider.lookupProtocol(ProtocolId.IPv4);

Protocol Configuration Provider

Provides protocol configurations for the ProtocolStack:

public interface ProtocolConfigProvider {
    
    int packId();
    String packName();
    
    <T extends ProtocolConfig> T findConfig(Class<T> type);
    ProtocolConfig findConfig(int protocolId);
}

Template Discovery

ProtocolTreeService provides named protocol tree templates optimized for different backends:

public interface ProtocolTreeService {
    
    boolean supports(String templateName);
    ProtocolTree createTemplate(String templateName);
}

Available Templates

Template	Description	Use Case
default	Full protocol tree	General purpose
pcap	L2-L4 only, no L5+	jNetPcap
dpdk	Optimized for DPDK backend	jNetWorks with DPDK
ntapi	Optimized for Napatech	jNetWorks with NTAPI

Template Usage

// Get template for backend
ProtocolTree template = ProtocolTreeService.getTemplate("pcap");

// Build runtime tree
ProcessorTree processors = ProtocolStackService.build(template, stack, backend);

Analyzer Plugins

Analyzers attach to processors and emit tokens. They are discovered via AnalyzerProvider:

public interface AnalyzerProvider {
    
    // Identification
    String name();  // "suricata", "custom-ml", etc.
    
    // Attachment point in processor tree
    Class<? extends Protocol> attachPoint();
    
    // Factory method
    Analyzer createAnalyzer();
    
    // Token types this analyzer produces
    long tokenMask();
    
    // Priority (lower = higher priority)
    int priority();
}

Implementing an Analyzer Provider

public class SuricataAnalyzerProvider implements AnalyzerProvider {
    
    @Override
    public String name() { 
        return "suricata"; 
    }
    
    @Override
    public Class<? extends Protocol> attachPoint() { 
        return TcpProtocol.class;  // Attach to TCP processor
    }
    
    @Override
    public Analyzer createAnalyzer() { 
        return new SuricataAnalyzer(); 
    }
    
    @Override
    public long tokenMask() { 
        return IdsTokens.ALERT | IdsTokens.FLOW_EVENT; 
    }
    
    @Override
    public int priority() { 
        return 100;  // Default priority
    }
}

Service Registration

Create file META-INF/services/com.slytechs.sdk.protocol.spi.AnalyzerProvider:

com.slytechs.sdk.protocol.ids.SuricataAnalyzerProvider
com.slytechs.sdk.protocol.ml.CustomMlAnalyzerProvider

Bitmask Pruning

Analyzers are only instantiated if their tokens are subscribed:

// Subscribe to IDS alerts
stack.subscribeTokens(IDS_LAYER, IdsTokens.ALERT);

// SuricataAnalyzer will be created and attached
// If no subscription, analyzer is null (zero cost)

Heuristics Plugins

Protocol heuristics detect protocols by payload inspection when standard routing (port numbers, protocol fields) is insufficient:

public interface ProtocolHeuristic {
    
    // Check if payload matches this protocol
    boolean matches(ProcessorContext ctx, LayerContext layer);
    
    // Protocol this heuristic detects
    Class<? extends Protocol> detectedProtocol();
    
    // Priority (lower = checked first)
    int priority();
    
    // Minimum payload bytes needed
    int minimumBytes();
}

Heuristic Provider

public interface ProtocolHeuristicProvider {
    
    // Get heuristics for a router's protocol
    List<ProtocolHeuristic> getHeuristicsFor(Class<? extends Protocol> routerProtocol);
}

Example: HTTP Detection Heuristic

public class HttpHeuristic implements ProtocolHeuristic {
    
    private static final byte[] GET = "GET ".getBytes();
    private static final byte[] POST = "POST".getBytes();
    private static final byte[] HTTP = "HTTP".getBytes();
    
    @Override
    public boolean matches(ProcessorContext ctx, LayerContext layer) {
        MemorySegment payload = ctx.payloadView().segment();
        if (payload.byteSize() < 4) return false;
        
        // Check for HTTP methods or response
        return startsWith(payload, GET) 
            || startsWith(payload, POST)
            || startsWith(payload, HTTP);
    }
    
    @Override
    public Class<? extends Protocol> detectedProtocol() {
        return HttpProtocol.class;
    }
    
    @Override
    public int priority() {
        return 100;
    }
    
    @Override
    public int minimumBytes() {
        return 4;
    }
}

Backend Context

Backend context provides capabilities and constraints for resolution:

public interface BackendContext {
    
    String backendType();  // "pcap", "dpdk", "ntapi"
    
    boolean hasCapability(Capability cap);
    
    // Hardware offload capabilities
    enum Capability {
        HW_IP_FRAGMENTATION,
        HW_TCP_SEGMENTATION,
        HW_TIMESTAMPING,
        HW_FILTERING,
        ZERO_COPY,
        HUGEPAGES
    }
    
    // Get backend-specific processor factory
    Optional<ProcessorFactory> getProcessorFactory(Class<? extends Protocol> protocol);
}

Backend Processor Substitution

Backends can provide optimized processor implementations:

public class NtapiBackendContext implements BackendContext {
    
    @Override
    public Optional<ProcessorFactory> getProcessorFactory(Class<? extends Protocol> protocol) {
        if (protocol == IpProtocol.class && hasCapability(HW_IP_FRAGMENTATION)) {
            return Optional.of(() -> new NtapiIpProcessor());  // Hardware-accelerated
        }
        return Optional.empty();  // Use default software processor
    }
}

Custom Protocol Pack Example

Complete example of creating a custom protocol pack:

1. Define Protocol Configuration

public class MyProtocol extends Protocol {
    
    private final BooleanProperty featureEnabled;
    private final IntProperty bufferSize;
    
    public MyProtocol() {
        super("myprotocol");
        this.featureEnabled = booleanProperty("feature.enabled", false);
        this.bufferSize = intProperty("buffer.size", 1024);
    }
    
    public MyProtocol enableFeature(boolean enable) {
        featureEnabled.setBoolean(enable);
        return this;
    }
    
    public MyProtocol bufferSize(int size) {
        bufferSize.setInt(size);
        return this;
    }
}

2. Implement Protocol Provider

public class MyProtocolProvider implements ProtocolProvider {
    
    @Override
    public int packId() { return 0x8000; }  // User-defined range
    
    @Override
    public String packName() { return "myprotocol"; }
    
    @Override
    public Protocol findProtocol(int protocolId) {
        if (ProtocolId.packOf(protocolId) == packId()) {
            return new MyProtocol();
        }
        return null;
    }
    
    @Override
    public <T extends Protocol> T findProtocol(Class<T> type) {
        if (type == MyProtocol.class) {
            return type.cast(new MyProtocol());
        }
        return null;
    }
}

3. Implement Processor

public class MyProcessor implements Processor {
    
    private final MyProtocol config;
    
    public MyProcessor(MyProtocol config) {
        this.config = config;
    }
    
    @Override
    public Packet processPacket(Packet packet, ProcessorContext ctx, LayerContext layer) {
        // Parse and process
        return packet;
    }
    
    // ... other methods
}

4. Register Services

META-INF/services/com.slytechs.sdk.protocol.spi.ProtocolProvider:

com.mycompany.protocol.MyProtocolProvider

5. Use in Application

ProtocolStack stack = new ProtocolStack();

stack.setProtocol(new MyProtocol())
     .enableFeature(true)
     .bufferSize(4096);