Skip to content

System State Machines: Aegis Packet Engine

This document defines the lifecycle states and transitions for the key components of the Aegis engine.

1. TCP Connection / Flow State Machine

Aegis tracks the state of TCP connections to manage flow table allocation and determine when to inspect or sweep connection metadata.

stateDiagram-v2
    [*] --> NEW : SYN Packet Received
    NEW --> ESTABLISHED : SYN-ACK / ACK Packet Seen
    ESTABLISHED --> CLASSIFIED : TLS Client Hello (SNI) / HTTP Host Found
    CLASSIFIED --> TERMINATING : FIN / RST Packet Received
    ESTABLISHED --> TERMINATING : FIN / RST Packet Received
    TERMINATING --> CLOSED : Timeout / Both FINs Seen
    CLOSED --> [*] : Flow Swept / Reclaimed

Transition Descriptions:

  • NEW: Connection created on the first packet (SYN).
  • ESTABLISHED: Handshake completed. Payload inspection active.
  • CLASSIFIED: Application signature (SNI, host, or protocol) determined. Payload inspection halts; packets are forwarded using cache actions.
  • TERMINATING / CLOSED: Tear-down initiated. Entry scheduled for eviction.

2. Dynamic Rule Reload Lifecycle (RCU Pattern)

Aegis allows rules to be updated at runtime without interrupting fast path worker execution.

sequenceDiagram
    participant WorkerThread as Worker Thread
    participant Global as Global Store
    participant ControlThread as Control/Admin Thread

    Note over WorkerThread, Global: Worker reads rules pointer
    WorkerThread->>Global: Load active_rules_ (Acquire/Consume)
    WorkerThread->>WorkerThread: Evaluate packets using ActiveRulesV1

    Note over ControlThread: Admin triggers reload
    ControlThread->>ControlThread: Parse new rules from disk
    ControlThread->>ControlThread: Allocate RuleTableV2
    ControlThread->>Global: Swap active_rules_ (Exchange V2 for V1)

    Note over WorkerThread, Global: New packet arrives
    WorkerThread->>Global: Load active_rules_ (Acquire)
    WorkerThread->>WorkerThread: Evaluate packets using ActiveRulesV2

    Note over ControlThread: Reclamation phase
    ControlThread->>ControlThread: Sleep (wait for in-flight packets to drain)
    ControlThread->>ControlThread: Deallocate RuleTableV1 (Safe Free)

3. Packet Buffer Lifecycle

The memory of packet data travels through a dedicated lifecycle to prevent allocations.

stateDiagram-v2
    [*] --> PREALLOCATED : Engine Start (Contiguous Array)
    PREALLOCATED --> INGESTION : Ingestion thread pops index from Free List
    INGESTION --> BALANCED : Loaded into SPSC queue
    BALANCED --> WORKER_INSPECT : Popped by Fast Path core
    WORKER_INSPECT --> OUTPUT_QUEUE : Action: FORWARD (ref_count maintained)
    WORKER_INSPECT --> RECLAIMED : Action: DROP (ref_count -> 0)
    OUTPUT_QUEUE --> WRITE_OUT : Written to PCAP by Writer
    WRITE_OUT --> RECLAIMED : Ref_count decremented to 0
    RECLAIMED --> PREALLOCATED : Index returned to Free List

4. Worker Thread Lifecycle

Fast Path worker threads run a deterministic loop to maximize throughput.

stateDiagram-v2
    [*] --> INITIALIZING : Pin to CPU Core, allocate local FlowTable
    INITIALIZING --> POLLING : Enter Spin-Loop
    POLLING --> PROCESSING : Packet available in SPSC input queue
    PROCESSING --> EVALUATE_FLOW : Extract 5-tuple
    EVALUATE_FLOW --> INSPECT_PAYLOAD : Flow not classified
    INSPECT_PAYLOAD --> APPLY_RULES : App detected / fallback
    EVALUATE_FLOW --> APPLY_RULES : Flow already classified
    APPLY_RULES --> FORWARD : Allow
    APPLY_RULES --> DROP : Block
    FORWARD --> POST_PROCESS : Push to Output Queue
    DROP --> POST_PROCESS : Reclaim Buffer Block
    POST_PROCESS --> SWEEP_FLOWS : Check timeout epoch (every 10k packets)
    SWEEP_FLOWS --> POLLING : Loop
    POLLING --> SHUTDOWN : Shutdown flag set
    SHUTDOWN --> [*] : Join thread