
This directory contains the implementation of TCP session tracking and
processing functions.  When the network protocol for a flow is determined
to be TCP the base Stream preprocessor will delegate handling of the
packets on that flow to this module.

The Stream TCP module is currently in process of a complete rewrite.  These
dev notes describe the current implementation.

The StreamTcp class is implemented as a subclass of Inspector and provides
functions for loading stream TCP configuration and packet evaluation.  The
packet eval method is not used as the base Stream Inspector delegates
packets directly to the TCP session packet processing method.

* TCP Segment Descriptor - this class provides access to the various fields of the TCP
  header and payload

* TCP Stream Tracker - this class encapsulates all the state information required for
  tracking one side of the TCP connection.  For each flow that is tracked there will be
  two instances of this tracker, one for each direction.

* TCP State Handler - abstract class interface that defines a method for handling each
  possible TCP event.  For each TCP state a subclass of this class is created with a
  state specific implementation for each event handling method.

* TCP State Machine - this class is the engine that dispatches processing to the correct
  event handling method of the handler for the current TCP state of the flow.

The TCP session module implements the following functions:

* TCP segment normalization. Variations in handling normalization are
  configured by policy.

* TCP connection tracking.  The state of the connection from the
  perspective of each end of the connection is tracked.

* TCP reassembly. Variations in handling reassembly are configured by
  policy.

* Event generation for anomalies detected while processing the TCP
  segments.

A TcpSession object is allocated for each TCP flow being tracked.  TCP
session state is maintained primarily in the TcpTracker data structure.
State information includes:

* policy settings

* list of tcp segments being reassembled

* TCP connection state

* paf state

* alert history

An instance of this data structure is allocated and managed for each end of
the connection.

The module tcp_ha.cc (and tcp_ha.h) implements the per-protocol hooks into
the stream logic for HA.  TcpHAManager is a static class that interfaces
to a per-packet thread instance of the class TcpHA.  TcpHA is sub-class
of ProtocolHA, declared in the stream/base area.  Thus each protocol
within 'stream' can have specific HA logic and interfaces.

TcpHAManager::process_deletion() is called when an TCP stream is being
destroyed and indicates to the stream & flow HA logic that a flow
deletion HA message needs to be emitted for the flow in question.
Tcp streams are both closed internally (e.g. FIN) and externally due
to cache timeout or pruning.  The calls to TcpHAManager::process_deletion()
in tcp/tcp_session.cc indicate a normal closure of a stream/flow.

TcpHA::create_session() is called from the stream & flow HA logic and
handles the creation of new flow upon receiving an HA update message.

TcpHA::deactivate_session() is called from the stream & flow HA logic to
place a session into standby mode.  Upon receiving an HA Update message,
the flow is first created if necessary, and is then placed into Standby
state.  deactivate_session() sets the TCP specific state for Standby mode.

One HA state transition is implemented within this TCP library.  In
TcpStreamSession::clear(), TcpHAManager::process_deletion() is invoked to
cause HA to generate a Deletion message for the target flow.  This handles
the case where a TCP session is being removed from from the flow cache due
to a timeout or pruning function.  Other normal TCP stream closure actions
are handled in the ../tcp/tcp_session.cc module.
